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nded Audience 


This manual provides both tutorial and reference material on the graphics 
capabilities of VAX BASIC. Readers are presumed to be familiar with VAX 
BASIC programming techniques; however, no prior knowledge of graphics 
programming is required. This manual should be used with the other two 
manuals in the documentation set. 


‘ociated Documents 


This manual is one of three manuals that form the VAX BASIC document 
set. The other two manuals are 


VAX BASIC Reference Manual Provides reference material and syntax for 
all VAX BASIC language elements except 
graphics capabilities 


VAX BASIC User Manual Provides tutorial material for VAX BASIC 
language constructs and information 
pertaining to programming with VAX 
BASIC on VAX/VMS systems 


You may also be interested in the following supplementary manuals: 


e VAX BASIC Syntax Summary 
e Introduction to BASIC 

e BASIC for Beginners 

¢ More BASIC for Beginners 
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Structure of This Document 


xvi 


This manual has nine chapters and two appendixes. 


The first eight chapters explain how to use the graphics capabilities of 
VAX BASIC. The remaining chapter consists of alphabetically arrange: 
reference descriptions of each VAX BASIC graphics statement. 


Programmers who have little or no experience using graphics should b 
with Chapter 1 and proceed with the chapters in sequence. Experienct 
graphics programmers may prefer to use the reference section (Chapte 
9) and the chapters concerned with more advanced graphics technique 
(Chapters 6 through 8). 


Chapter 1 
Chapter 2 


Chapter 3 
Chapter 4 
Chapter 5 
Chapter 6 
Chapter 7 
Chapter 8 


Chapter 9 


Appendix A 
Appendix B 


Introduces you to VAX BASIC Graphics and the main 
categories of graphics statements 


Shows you how to put some simple graphics objects on y 
screen 


Shows you how to change the appearance of objects 
Explains how to change text attributes 

Explains the coordinate systems 

Describes how to create complex images 

Describes various ways of providing input for graphics 


Explains how to use multiple devices and device transforn 
tions 


Lists the rules and syntax for all VAX BASIC graphics 
statements 


Describes how to call VAX GKS directly 


Provides device-specific information 


mventions Used in This Document 


Convention Meaning 
$ ASSIGN In command-line examples, the user’s response to 


a prompt is printed in red; system prompts are 
printed in black. 


A vertical ellipsis indicates that code which would 
normally be present is not shown. 


UPPERCASE letters Uppercase letters are used for VAX BASIC 
keywords and must be coded exactly as shown. 


lowercase letters Lowercase letters are used to indicate user- 
supplied names or characters. 


Conventions used in the syntax diagrams in Chapter 9 are listed at the 
start of that chapter. 
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ummary of New and Changed Features 
br Version 3.0 


Version 3.0 of VAX BASIC includes extensive graphics capabilities, struc- 
tured error handling techniques, enhancements to file I/O and other new 
features. All of these features are documented in the VAX BASIC Reference 
Manual and the VAX BASIC User Manual except for the graphics features, 
which are documented in this manual. This section summarizes all of the 
major changes for this release. 


Graphics Capabilities 


VAX BASIC supports extensive graphics capabilities based on VAX GKS. 
The new graphics capabilities are available to you if you have the full or 
run-time VAX GKS kit installed on your system (Version 2.0 or later) and 
if you use supported graphics hardware. The main features of VAX BASIC 
graphics are as follows: 

e A short learning period 

¢ Convenient default values for attributes 

¢ Statements consisting of English words in simple constructs 

¢ Window and viewport settings that are easy to alter 


¢ Graphics subprograms that can be invoked with a variety of transfor- 
mation functions 


¢ Input statements for interactive graphics programs 
e Programs that can run on multiple devices 
¢ Programs that run on any hardware supported by VAX GKS 


Structured Error Handling 


VAX BASIC supports structured error handling with WHEN ERROR 
constructs. When an error occurs during execution of statements in a 
protected block of code, the error is handled by the associated attached or 
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XX 


detached handler. The following new statements and functions enhanc 
error-handling capabilities: 

e WHEN ERROR 

e RETRY 

¢ CONTINUE 

e HANDLER, EXIT HANDLER, and END HANDLER 

¢ OPTION HANDLE 

e CAUSE ERROR 

¢ RMSSTATUS and VMSSTATUS 


Although the new WHEN ERROR constructs are the preferred method 
for error handling, ON ERROR statements are supported for compatibili 
with previous versions of BASIC. 


Optional Line Numbers 


Line numbers are no longer required in VAX BASIC programs. A VAX 

BASIC program can have no line numbers at all, or it can use the tradi- 
tional line-numbered statements; both are valid. A program with a line 
number on the first nonblank line is treated as a line-numbered prograr. 
by the compiler. In the BASIC environment, programs with no line nun 
bers must be created with a text editor or copied into the environment 

with the OLD command. 


Array Bounds 


You can now specify the lower bound for any or all dimensions of non- 
virtual arrays. Previously, VAX BASIC arrays could only be zero-based. 
In addition, two new functions, LBOUND and UBOUND, allow you to 
retrieve the lower and upper bounds of array dimensions. 


Improvements for Procedure Invocations 


This version of VAX BASIC includes additional flexibility for procedure 
invocations: 


e If an external function is called as a procedure, VAX BASIC perform 
parameter validation exactly as if the declared function had been 
invoked as a function. 


e The new keywords ANY and OPTIONAL ease parameter passing tc 
non-BASIC routines. 
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e Additional functionality has been added to the LOC function so that 
the address of an external function can be accessed. 


PRINT USING Format Strings 


Constant PRINT USING format strings are precompiled at compile time. 
Significant run-time performance gains can be achieved by recompiling 
programs that use constant format strings. 


Single Keystroke Input 


The new function INKEY$ allows you to detect a single keystroke typed at 
a terminal. Function and keypad keys return a descriptive text string, for 
example, “F17”, and control characters return a single ASCII code. 


1/0 Enhancements 
The following features have been added to enhance I/O capabilities: 


e STREAM files are accessible with the OPEN statement. 


e A WAIT clause can be added to the GET and FIND statements. This 
clause instructs VAX BASIC to wait on locked records rather than 
immediately returning the error RECBUCLOC (ERR = 154). 

¢ The new keywords NX (next) and NXEQ (next or equal to) are syn- 
onyms for GT and GE respectively. These keywords make the GET 
and FIND statements more meaningful if an indexed file is accessed 
with descending keys. 


Miscellaneous Features 


_¢ The new PROGRAM statement allows you to optionally name a main 
program unit. This name becomes the module name of the compiled 
source. 

e You can return a procedure value or the status of an image upon 
exiting with the following statements: 


— END/EXIT PROGRAM 
— END/EXIT FUNCTION 
— END/EXIT DEF 


e By default, VAX BASIC calls VAX EDT from the environment. The 
user or the system manager can select callable VAX EDT, the VAX 
Text Processing Utility (VAXTPU), or the VAX Language Sensitive 
Editor as the default editor. Start-up time for editing files within 
the environment is shorter as it is no longer necessary to spawn a 
subprocess to access editors that are callable. 
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System managers can prevent users escaping to DCL level from the 
environment by setting the user’s subprocess limit (PRCLM) to zero. 
A subprocess limit of 1 was previously required so that a user could 
use an editor within the environment. 


New extensions to the OPTION statement include the following: 
— OPTION ANGLE = degrees-or-radians 

— OPTION HANDLE = severity-level 

— OPTION CONSTANT TYPE = data-type 

— OPTION OLD VERSION = CDD 


The MID§ function can now be on the left side of an assignment 
statement. This feature allows partial string replacement. 


VAX BASIC statements, compiler directives, labels, and comment line 
can now start in column 1. 

You can include files from a text library with the %INCLUDE 
directive. 

The suffixes $ (for strings) and % (for integers) are allowed on explic: 
itly declared variables and constants. 

Extensions to the REMAP and MAP DYNAMIC statements allow you 


to redefine the storage allocated to a previously declared static string 
variable. 


New functions MAX and MIN are provided for the comparison of a 
series of arguments. 


The new MOD function divides one numeric argument by another 
and returns the remainder. 


The new compiler directive %PRINT allows you to print a message 
during the compilation of a source program without aborting the 
compilation. 

The new lexical directive %DECLARED allows you to determine 
whether or not a lexical variable has been declared. 


Chapter 1 


Introduction to VAX BASIC Graphics 


VAX BASIC graphics statements have been designed so that you can create 
and manipulate pictures and incorporate graphics into your applications 
programs. 


1 Overview 


With VAX BASIC graphics statements you can: 


Draw lines and geometric shapes 

Display points with various markers 

Display text in various fonts and sizes 

Fill a defined area with various patterns 

Alter window sizes 

Accept input interactively 

Create graphs and designs 

Create complex images with graphics subprograms 


These graphics are applicable over a wide range of conventional graphics 
hardware. A VAX BASIC program containing graphics statements can be 
run on any system running VAX/VMS Version 4.5 or higher that has VAX 
GKS Version 2.0 or higher installed. 


VAX GKS provides extensive two-dimensional graphics capabilities; VAX 
BASIC provides an interface between your program and VAX GKS. The 
building blocks of this interface are illustrated in Figure 1-1. Single 
language statements allow you to easily access the capabilities of VAX 
GKS from within a VAX BASIC program. 
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Figure 1-1: Building Blocks of VAX BASIC Graphics 
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1.2 Before You Begin 


1-2 


The examples in this manual will run on any hardware supported by 
VAX GKS (although some examples may require changes for a particular 
terminal). Devices supported by VAX GKS include VT125 and VT240 
terminals, both monochrome and color, and VAXstations I, II, and II/GP. 
Each of these devices has a designated number that VAX GKS recognize: 


and associates with the actual device. 


Before writing VAX BASIC graphics programs, you should inform VAX 
GKS of your terminal type by assigning the designated number for your 
device to the logical name GKS$WSTYPE. You do this with the DCL 
command ASSIGN. The following command informs VAX GKS that you 
are using a VT240 terminal with color capabilities (device type 13). 


$ ASSIGN 13 GKS$WSTYPE 


Introduction to VAX BASIC Graphics 


If you do not assign the appropriate value to GKS$WSTYPE, VAX BASIC 
uses the system default device type (if one has been assigned). To find 
out which device type has been assigned to GKS$WSTYPE, enter the 
following command: 


$ SHOW LOGICAL GKS$WSTYPE 


If no translation is available for GKS$WSTYPE, VAX BASIC assumes 
that you have a monochrome VT240 (device type 14). A complete list 
of supported devices is provided in Chapter 9 under the OPEN...FOR 
GRAPHICS statement. Once you have established your terminal type, 
you should assign this value to the logical name GKS$WSTYPE in your 
login command procedure. 


The quality of the generated image varies according to the display device 
that you use. The larger the number of pixels, the higher the resolution of 
the graphics image. Similarly, the quality of color in the images produced 
by VAX BASIC graphics programs is limited by the quality of the display 
device you use. 


.3 VAX BASIC Graphics Statements 


VAX BASIC graphics statements consist of English words (such as SET, 
ASK, and PLOT) in simple constructs. The statements are therefore easy 
to remember and comprehend. For example, the following statement 
accepts the coordinates of a single point from the keyboard: 


LOCATE POINT x,y 
The following statement increases the height of the text to a value of 0.05: 
SET TEXT HEIGHT 0.05 


VAX BASIC graphics statements can be grouped into the seven main 
categories listed in Table 1-1. 
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Table 1-1: Categories of VAX BASIC Graphics Statements 
Statement Category Purpose 


Output statements Draw graphics images such as points, lines, an 
areas, and also write text. 


Attribute statements Specify the exact appearance of a graphics 
object, for example, the style, size, thickness, 
and color of a line. 


Picture statements Define an output display in a fashion similar 
to VAX BASIC subprograms. When drawn, 
pictures can be shifted, scaled, sheared, and 
rotated. 


Input statements Accept input from various hardware devices 
such as a mouse or a keyboard. 


ASK statements Retrieve the current value of an attribute. The 
current value is assigned to a variable you 
supply. 

Coordinate statements Provide you with a means of expressing the 
relative position of an object and how much 
of a display should be shown, and allow you 
to limit the display to a particular area on the 
display surface. These statements ultimately 
affect the visible output on the display screen. 


Control statements Manage the opening and closing of VAX GKS, 
the initialization and selection of devices, and 
the clearing of display surfaces. 


A typical VAX BASIC graphics program includes statements from several 
of these groups. The following sections provide more information on eact 
group of statements. 
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3.1 Output Statements 


VAX BASIC provides several statements for drawing objects, including 
GRAPH POINTS, GRAPH LINES, GRAPH AREA, and GRAPH TEXT. 
You must supply VAX BASIC with information about where to place 
graphics objects on the display surface. You can do this with a simple 
coordinate system. For details about coordinate systems, see Section 1.3.6 
and Chapter 5. 


You separate the coordinates of a single point with a comma. Pairs of 
coordinates must be separated by a semicolon. Note that you cannot use 
parentheses to enclose the coordinates of a point as is customary in other 
representations of points; VAX BASIC signals an error if you do so. 


The following statement marks a single point x,y with an asterisk on the 
display surface: 


Example 
GRAPH POINTS x,y 


Output 


ee ee— ee 
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The following GRAPH statement draws a line from the first to the secon 
point, the second to the third point, and so on to complete a square: 


Example 
GRAPH LINES 0,0; 0,0.5; 0.5,0.5; 0.5,0; 0,0 


Output 


(CS 





ee 
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PLOT statements provide additional capabilities for output. Chapters 2 
and 6 discuss how to use the GRAPH and PLOT statements. 


1.3.2 Attribute Statements 


A graphics object has several attributes. For example, style, size, thickness 
and color are all attributes of a line. Each attribute has an initial default 
value; for instance, the style of a line is solid at the start of program 
execution. You can change the default style to produce a line of dots or 
dashes. Unless you explicitly change specific attributes, graphics objects 
are displayed with the default values. 


The SET statement allows you to assign the attributes of your choice to 
a graphics object from within a program. For instance, in the previous 
GRAPH POINTS example, the point displayed on the screen is of the 
default style, an asterisk. Instead of an asterisk, you can specify that a 
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point be displayed with one of several alternative marker styles. In the 
following example, the value 5 as an argument to the SET POINT STYLE 
statement produces a diagonal cross as the marker for the point. 


SET POINT STYLE 5 
GRAPH POINTS x,y 


Output 


EEN. 


ee ee ene ee 
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Similarly, you can change the text font so that characters are displayed 
with a hardware font rather than the default software font. To do this, 
you can include the following statement before drawing text: 


SET TEXT FONT -1, "CHAR" 


Chapters 3 and 4 describe the possible attributes for graphics objects and 
explain how to select them. 


Introduction to VAX BASIC Graphics 1-7 


1.3.3 Picture Statements 
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A routine for drawing a particular image can be defined in a picture, a 
graphics subprogram. You can subsequently draw the picture and alter 
the original image by shifting, scaling, rotating, or shearing. Pictures can 
also be drawn recursively. You invoke a graphics picture with the DRAW 
statement. In the following example a triangle is defined in a picture and 
later invoked with the DRAW statement: 


Example 


PICTURE Triangle(SINGLE x,y) 

t+ 

!Draw triangle with varying third point 

{- 

GRAPH LINES 0.3,0.7; 0.6,0.7; x,y; 0.3,0.7 
END PICTURE 


PROGRAM Triangle_demo 
EXTERNAL PICTURE triangle (SINGLE, SINGLE) 
i+ 


! Invoke the picture naming a third point 
t 


DRAW Triangle(0.4,0.2) 
'+ 
! Invoke the picture with a different third point 


t- 
DRAW Triangle(0.1,0.2) 
END PROGRAM 


Introduction to VAX BASIC Graphics 


Output 


\ | ) 
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Chapter 6 discusses graphics pictures; it explains parameter passing, 
picture definitions, and how to make changes in the picture image. 


Two libraries of pictures are included with your VAX BASIC kit: 

a text library (BASIC6GRAPHICS.TLB) and an object library 
(BASIC$6GRAPHICS.OLB). These libraries contain useful routines 
that you can use in your own programs. Both of these libraries 
reside in SYS$SYSROOT:[SYSHLP.EXAMPLES.BASIC]. Files from 
the object library can be linked with main programs; source files 
from the text library can be included in your programs with the 
%INCLUDE directive. 
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1.3.4 


Input Statements 


VAX BASIC graphics programs accept data from an input device in a 
fashion similar to the INPUT and MAT INPUT statements. However, 
graphics data is accepted by the LOCATE and MAT LOCATE statements. 
In addition to entering the data as characters on a keyboard, a user can 
supply the data by positioning a mouse, by positioning a cursor on a 
menu selection, or by other means. 


SET statements allow you to set up the screen display presented to a 
user. For instance, the following example shows how to set up a list of 
menu choices to be presented to a user. A subsequent LOCATE CHOICE 
statement displays the menu and accepts the user’s selection. 


Example 
SET INITIAL CHOICE & 
, LIST ("view* & 
, "update" & 
, "delete" & 
»"quit") & 


: 1 
LOCATE CHOICE to_do 


Chapter 7 shows you how to use the graphics input statements. 


1.3.5 ASK Statements 
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At any point in your program you can ask for the current value of an 
attribute. You request the value with an ASK statement, and the value 
returned is assigned to a variable you supply. The ASK statement re- 
trieves the current value of the attribute, that is, the value that would 
apply if an output statement were performed at that time. Values for 
common attributes are provided in the appropriate chapters. The follow- 
ing statements are examples of ASK statements. Note that in graphics 
programs, floating-point variables should be declared as SINGLE, and 
integers should be declared as LONG. 
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Example 


DECLARE LONG what_color,which_style,point_size, & 
SINGLE how_tall 


ASK TEXT COLOR what_color 
ASK TEXT HEIGHT how_tall 
ASK LINE STYLE which_style 
ASK POINT SIZE point_size 


Within a program, you can ask for current attribute values, change the 
attribute values, and later use the stored values to restore the previous 
settings. The ASK statements are also useful for determining the par- 
ticular capabilities of the devices that you use and adapting your pro- 
grams accordingly. The ASK statements are described in various chapters 
throughout the manual. 


3.6 Coordinate Statements 


You must supply VAX BASIC with information about where to place the 
graphics object on the display surface. To supply this information in terms 
of pixels on the screen would be tedious. Instead, you can supply the 
information by using a simple coordinate system. You express a point 

in terms of its relative position from specified x- and y-axes on your 
display surface. This way, any point on your screen can be described by 
a pair of coordinates. VAX BASIC transforms your coordinates into the 
actual coordinates for a supported device automatically so that you do not 
have to write various versions of your program to accurately position the 
display on a specific output device. 


VAX BASIC provides statements that allow you to manipulate the display 
of a graphics object. You can select just a section of the screen for a 
display, you can overlay one image with another, or you can build up one 
large image from several smaller images. Chapters 5, 6, and 8 discuss how 
to control the positioning of images on an output device. 
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1.3.7 Control Statements 


Control statements add flexibility to your programs. They allow you to 
use an alternate output device, or even use several devices at one time. 
Statements such as the following allow you to control when and where 
display from your program is activated. 


Example 


OPEN "VT70:" FOR GRAPHICS AS DEVICE #2 


CLOSE DEVICE #2 


When VAX BASIC opens a device for graphics, the screen is automatical 
cleared. 


Unless you plan to use a device other than the terminal at which you 
enter the program, you need not be concerned with these statements. 
Chapter 8 provides details on how to use control statements. 


1.4 Using VAX BASIC Defaults 
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For most purposes, VAX BASIC provides you with useful default values. 
If you are programming a display to appear on your current terminal, fo: 
instance, you need not supply a device identification number; unless you 
state otherwise, VAX BASIC assumes that you are referring to your curre! 
device. Similarly, a square region of your screen is used as the default 
area for your display unless you specify a different section as your outpu 
area. It follows that you can keep your graphics programs simple when 
you wish to. 


The following example shows a simple graphics program that uses only 
the default values. The program draws a box on the terminal screen and 
then places text inside the box. The built-in VAX BASIC defaults are use: 
for the style and thickness of the line, the text font and size, the device, 
and the amount of the screen used for the display. 
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Example 


PROGRAM Sample 
OPTION TYPE = EXPLICIT 
DECLARE SINGLE CONSTANT x 


0.1 & 
y 0.1 


'+ 
! Connect four points to form box 


PLOT LINES x,y; x,y+0.2; x+0.65,y+0.2; x+0.65,y; x,y 


t+ 


! Place the text in the box 
1- 


GRAPH TEXT AT x, y + 0.08 : "These words fit in the box" 
END PROGRAM 


Output 


(CS 


These words fit in the box 





ee eee ne ee 
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When you do require values other than the defaults, you can change the 
defaults by supplying the appropriate values with the SET statement. 
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1.5 Program Development Options 


As with other VAX BASIC programs, you can develop a graphics prograr 
within the BASIC environment as well as directly at DCL level. Executab! 
graphics statements can be run in immediate mode. Statements that 
conflict with compiler commands (such as the SET statement) can be 
entered in immediate mode provided that each statement is preceded wit 
a backslash (\). 


VAX BASIC graphics capabilities are fully integrated with the VAX/VMS 
program development tools. For instance, the optional VAX Language- 
Sensitive Editor includes extensive language definitions for VAX BASIC 
graphics statements. Similarly, you can locate run-time errors in a VAX 
BASIC graphics program with the VAX/VMS Debugger. 


Error messages related to graphics are listed in the VAX BASIC User 
Manual along with all other error messages for VAX BASIC. 


1.6 Graphics Standards 
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The Graphical Kernel System (GKS) has been adopted as the Internation: 
Standard by the International Organization for Standardization (ISO) and 
the American standards body, ANSI. The main objective of GKS is to 
create and manipulate graphics images independently of the computer or 
device being used. 


The VAX BASIC graphics package is based on DIGITAL’s implementatior 
of GKS on VAX/VMS systems, VAX GKS. Many VAX BASIC graphics 
statements correspond directly to one or more of the VAX GKS routines 
described in the VAX GKS documentation. The VAX BASIC graphics 
statements provide many of the capabilities described in VAX GKS and, 
therefore, many of the capabilities prescribed by the ISO. 
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Chapter 2 


Displaying Graphics Objects 





This chapter shows you how to use the graphics statements GRAPH, 
PLOT, MAT GRAPH, and MAT PLOT to display points, lines, areas, and 
text on your screen.! 


1 The Default Drawing Board 


Before you can direct VAX BASIC to display a point on your terminal 
screen, you have to consider where the point should be and how you 
can specify that position. To specify the position of a point, you use a 
coordinate system. The coordinate system you use to specify a point to 
VAX BASIC is the Cartesian system; it consists of a two-dimensional 
coordinate plane (referred to here as the default drawing board). 


The default drawing board is usually a square region of your terminal 
screen, although this is dependent on the particular device you use. For 
instance, if you have a VT125 or VT240 terminal, the default drawing 
board fills the largest square region that it can, starting with the lower left 
corner of the screen. Figure 2-1 illustrates the default drawing board. 


1 On VAXstations, output is displayed on a new window and the output display disappears when the new 
window is closed. There are various ways to keep the output display active; for instance, you can include 
SLEEP statements in your programs. 
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Figure 2-1: The Default Drawing Board on a VT125 Termin 


Point 0.5, 0.3 
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The coordinate system consists of two perpendicular axes with an origin 
zero. The x-axis extends to infinity, increasing positively to the right anc 
negatively to the left. The x-axis is the horizontal axis in the coordinate 
plane: the default x-axis extends along a section of the base of your 
screen. The y-axis also extends to infinity, but increases positively upwai 
and negatively downward. The y-axis is the vertical axis: the default 
y-axis bounds your screen on the extreme left. 


With Cartesian coordinates, you define the position of a point by its dis- 
tance from the x- and y-axes. The x-coordinate of a point is the horizonti 
distance from the vertical axis to the point. The y-coordinate of a point is 
the vertical distance from the horizontal axis to the point. When a point 
specified, the coordinates are separated by a comma, for instance x,y. 


NOTE 


Coordinates of a single point must be separated by a comma. 
Pairs of coordinates must be separated by a semicolon. You 
cannot use parentheses to enclose the coordinates of a point 

as is customary in other representations of points; VAX BASIC 
signals an error if you do so. However, parentheses are allowed 
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when expressions are supplied as coordinate values. The 
following examples show valid syntax for the coordinates for a 
single point: 


e 0.5,0.8 
e x,y 
© 0.1,(0.1 + y) 


©  1/5,2/7) 


Distance is the abstract measurement of the length of each axis. For the 
default drawing board, the distance is specified on a scale of 0 to 1. Each 
axis begins at 0 at the bottom left corner of your screen and extends to 1 
at the end of each axis. (Note that the axes actually extend to infinity; the 
limits of 0 through 1 are imposed only for the default drawing board.) For 
the default drawing board, the coordinate pair 0,0 specifies the point of 
intersection between the two axes at the lower left corner of your screen. 
The coordinate pair 0.5,0.5 specifies a point in the center of the drawing 
board. Figure 2-1 illustrates the specifications for the point 0.5,0.3 on the 
default drawing board of a VT125 screen. 


Throughout this manual the variables x and y represent the x- and y- 
coordinates of the point on your screen. Notice that any objects plotted 
with negative coordinate values, or values greater than 1, are beyond the 
scope of the default drawing board and therefore are not displayed on 
your screen. For instance, the points 5,7 and -2,3 are not displayed on the 
default drawing board. You can supply a value from 0 through 1 with up 
to six digits of precision; however, the precision in a display is dependent 
on the quality of the graphics output device you use. 


For more information about coordinates and how to change the default 
drawing board with the SET WINDOW statement, see Chapter 5. 
Chapter 5 shows you how to alter the drawing board so that the coor- 
dinates of a point can have values of less than 0 and more than 1. The 
examples in this chapter and Chapters 3 and 4 are limited to the default. 
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2.2 Displaying Points 


The GRAPH POINTS statement displays one or more points on your 
screen. To display points, GRAPH POINTS must be followed by one 
coordinate pair for each point. To display a single point, supply one pai 
of coordinates, for example: 


GRAPH POINTS 0.1,0.5 


GRAPH POINTS marks the point with the default point style, an asteris] 
(*). To display several points, separate each coordinate pair with a 
semicolon (; ). 


Example 

GRAPH POINTS 0.1,0.5; & 
0.3,0.6; & 
0.45,0.475; & 
0.5,0.29;  & 
0.45,0.14; & 
0.625,0.14; & 
0.7,0.3 

Output 
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3 Displaying Lines 


The GRAPH LINES statement displays one or more lines on your screen. 
You must provide both a starting point and an ending point for the line. 
Therefore, you must supply GRAPH LINES with the coordinates for at 
least two points. To draw one line, supply GRAPH LINES with two 
coordinate pairs separated by a semicolon (;). 


GRAPH LINES 0.8,0.2; 0.7,0.8 


GRAPH LINES connects these two points with the default line style, a 
solid line. 


When you supply several coordinate pairs as parameters, GRAPH LINES 
draws a line from the first point to the second point, from the second 
point to the third, from the third to the fourth, and so on. 


Example 

GRAPH LINES 0.1,0.5; & 
0.3,0.6; & 
0.45,0.475; & 
0.5,0.29;  & 
0.45,0.14; & 
0.625,0.14; & 
0.7,0.3 
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Output 
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You can also use GRAPH LINES to draw closed shapes. The next exam 
uses the same seven points and two GRAPH LINES statements to draw 
quadrilateral and a triangle. In each case the first point must be supplie: 
again as the last point so that the closing line is drawn. 
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Example 


'+ 

!Supply three points and repeat the first 
!'to enclose a triangle. 

1- 

GRAPH LINES 5; 
6; 
0.475; 
5 


0.1,0 
0.3,0 
0.45, 
0.1,0 
t+ 

!Supply four points and repeat the first 


!'to enclose a quadrilateral 
t- 


GRAPH LINES 0.5,0.29; & 
0.45,0.14; & 
25,0.14; & 


0.6 
0.7,0.3; & 
0.6,0.29 


Output 


(CS 


aN 


[/ 


ne eee ee 4 
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The following example shows the GRAPH LINES statement used within 
a FOR...NEXT loop to draw a 10 by 10 grid. When displayed on your 
screen, this grid covers the default drawing board. You can use such a 
grid to sketch drawings and to calculate the coordinates of points you 
want to use in your programs. 
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Example 


OPTION TYPE = EXPLICIT 
DECLARE SINGLE counter 
FOR Counter = O TO 1 STEP 0.1 
1+ 
!Draw the horizontal lines 
1- 
GRAPH LINES Counter,0.0; Counter,1.0 
f+ 
!Draw the vertical lines 
t- 
GRAPH LINES 0.0,Counter; 1.0,Counter 
NEXT Counter 
GRAPH LINES 0.0,1.0; 1.0,1.0; 1.0,0.0 
END 


Output 
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You can display lines with the PLOT LINES statement as well as the 
GRAPH LINES statement. However, PLOT LINES provides you with 
additional control over the display, as described in the following section. 
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-4 Controlling the Beam of Light 


When you write with a pencil on paper, you often raise the pencil to move 
from one position to another. While the pencil is in the air, it leaves no 
mark or trail on the paper. When you press the pencil onto the paper, the 
pencil marks the paper with a trail or line. 


A similar concept exists in computer graphics. In computer graphics you 
have the ability to switch a beam of light on or off. When the beam of 
light is switched off, it is possible to move a plotter from one position 
to another without leaving a trail or a line. When the beam of light is 
switched on, a plotter draws a line as it moves from one position to the 
next. In the case of graphics printers, the beam of light is analogous to a 
laser beam or ink jet. 


The PLOT LINES statement gives you control over whether the beam of 
light is left on after drawing the specified line. To leave the beam on, put 
a semicolon at the end of the last point in a PLOT LINES statement. To 
switch the beam off, use a PLOT LINES statement with no points, or with 
no semicolon at the end of a point list. The following statement switches 
the beam of light on because it ends with a semicolon. 


PLOT LINES 0.65,0.2; 


The beam of light is on, but no line is plotted because only a starting 
point is specified. If another point is supplied in a further PLOT LINES 
statement, as in the next example, the beam of light will leave a trail from 
point 0.65,0.2 to the point in the next statement supplied, 0.3,0.75. 


PLOT LINES 0.65,0.2; 
PLOT LINES 0.3,0.75 


After the point 0.3,0.75 has been reached, the beam is switched off 
because there is no semicolon at the end of the statement. A further 
PLOT LINES statement would not be connected to the point 0.3,0.75, as 
the beam is off. The positioning of the semicolons controls the light beam. 
Consider the output from the following example. 
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Example 


PLOT LINES 0.65,0.2; !Leave the beam on 

PLOT LINES 0.3,0.75 !Switch the beam off 

PLOT LINES 0.1,0.5; !Leave the beam on 

PLOT LINES 0.25,0.9; 0.75,0.75 !Switch the beam off and display output 


fpr, 
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The PLOT LINES statement can include coordinates for just one point 
only when the statement ends with a semicolon, or when the beam was 
already left on by a previous statement. This feature is useful when a 
sequence of points can be calculated in a formula and each new point 
supplied to the PLOT LINES statement in a program loop. The following 
example shows how the PLOT LINES statement can be used within a 
FOR...NEXT loop to draw an approximation of a sine curve. (Note that 
adjustments to the standard formula have been made to accommodate the 
default drawing board.) 
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Example 


OPTION TYPE = EXPLICIT 

DECLARE SINGLE turn,x,y 

$+ 

!Plots an approximation of a sine curve 
i 


FOR turn = 0 TO 2 * PI STEP 0.1 
x = (turn/(2 * PI)) 
y = ((SIN(turn) * 0.5) + 0.5) 
PLOT LINES x,y; 

NEXT turn 

I+ 


!Switch off the beam and display output 
f- 


PLOT LINES 
END 


Output 


NG 
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Each pass through the loop leaves the light beam on because of the 
semicolon at the end of the PLOT LINES statement. The final PLOT 
LINES statement outside the FOR...NEXT loop switches off the light beam 
as no points are supplied. You can also switch off the light beam with any 
other graphics statement, except another PLOT LINES statement with a 
semicolon. 
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Points connected with PLOT LINES statements that leave the beam on 
are not actually displayed one at a time; the output is stored untila | 
graphics statement switches off the beam. When the beam is switched 
off, the output is displayed. In the previous example, the sine curve is not 
displayed until the PLOT LINES statement outside the loop is executed. 
If the beam is not switched off during program execution, VAX BASIC 
displays the output when the program terminates. 


Note that the standard formula for a sine curve gives coordinate values 
of greater than 1 and less than 0; the sine curve would therefore extend 
beyond the boundaries of the default drawing board. Chapter 5 shows 
how to change the default drawing board and provides an example of 
displaying a full sine curve. 


The following partial program uses the PLOT LINES statement to display 
an oval. 


Example 


OPTION TYPE = EXPLICIT 
DECLARE SINGLE turn, x, y, & 
LONG I 

FOR I = 0 TO 40 
Turn = 2 * PI * I/40 
x = (SIN(Turn) + 1)/2 
y = (COS(Turn) + 1)/4 
PLOT LINES x,y; 

NEXT I 

t+ 

{Switch off the beam 

{- 

PLOT LINES 

END 
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Output 
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Use the PLOT LINES statement when you need to control the beam of 
light in the display area or when you want to draw lines connecting points 
that are supplied only one at a time. Use the GRAPH LINES statement 
when you can supply at least two points at a time and when you do not 
need to control the beam of light. The PLOT statement has additional 
functions that this section has not addressed. For more information about 
the PLOT statement, see Chapter 6. 


2.5 Displaying Areas 


You can outline shapes with GRAPH LINES or PLOT LINES statements. 
VAX BASIC also provides you with a method of displaying the area of 
a shape. The GRAPH AREA statement allows you to fill the area of a 
shape. The default fill style for GRAPH AREA is solid. 
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Example 


Output 





eee eee er 
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Notice that the first point does not need to be repeated for the GRAPH 
AREA statement. The following two statements both produce a triangle: 
the GRAPH LINES statement draws the outline using four points, and the 
GRAPH AREA statement fills the area using three points. 
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Example 


1+ 


!Only three points supplied for the area of a triangle 
t- 


t+ 
!The first point must be repeated for the triangle outline 


GRAPH LINES 


The following statement displays the area of the default drawing board on 
your screen. 


GRAPH AREA 0.0,0.0; 0.0,1.0; 1.0,1.0; 1.0,0.0 


2.6 Displaying Text 


You often need to position text on the screen as precisely as you position 
diagrams. The GRAPH TEXT statement allows you to supply the text you 
want displayed as well as the exact starting position. The starting position 
must be a coordinate pair. The text can be any string expression following 
a colon (:). 
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Example 


DECLARE STRING CONSTANT selection = “or" 
GRAPH TEXT AT 0.1,0.8 : "You could place the words here" 


GRAPH TEXT AT 0.7,0.6 : selection + " here" 
GRAPH TEXT AT 0.2,0.4 : selection 
GRAPH TEXT AT 0.2,0.3 : "HERE" 
GRAPH TEXT AT 0.2,0.2 : "or" 
GRAPH TEXT AT 0.5,0.1 : “anywhere else" 
Output 
You could place the words here 
or here 
or 
HERE 
anywhere else 


Ne 
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You can easily label a diagram with the GRAPH TEXT statement, as 
shown here: 


Example 


GRAPH LINES 0.3,0.6; 0.7,0.6; 0.7,0.2; 0.3,0.2; 0.3,0.6 
GRAPH LINES 0.45,0.2; 0.45,0.4; 0.55,0.4; 0.55,0.2 
GRAPH AREA 0.3,0.6; 0.5,0.75; 0.7,0.6 

GRAPH TEXT AT 0.3,0.8 : "Your BASIC House" 


Output 


(ES 


Your BASIC House 





eee ee 
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You can use VAX BASIC built-in functions to format string or numeric 
expressions. For example, you can format a numeric expression with 
the function FORMAT$. Both of the following GRAPH TEXT statements 
display the same output: 

Example 


DECLARE STRING format_string 
GRAPH TEXT AT 0.1,0.5 : FORMAT$(100000, "$$##, ###") 


format_string = FORMAT$(100000, "$$##, ###") 
GRAPH TEXT AT 0.1,0.4 : format_string 


Output 
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7 Supplying Coordinates in Arrays 


When you have many points to supply to a graphics statement, it can be 
more convenient to use arrays than to list each individual coordinate. VAX 
BASIC provides two types of graphics statements that display coordinates 
from arrays: MAT GRAPH and MAT PLOT. The MAT PLOT statements 
are discussed in Chapter 6. The following sections discuss the MAT 
GRAPH statements. 


In a GRAPH statement, each point is represented by two coordinates: 

an x- and a y-coordinate. Similarly, in a MAT GRAPH statement each 
point is represented by two coordinates: an x-coordinate supplied in 

a one-dimensional array, and a y-coordinate supplied in another one- 
dimensional array. You supply the MAT GRAPH statement with two 
whole arrays: one array of x-coordinates and one array of y-coordinates. 
The first point is specified by the first element in the first array (x-array) as 
the x-coordinate, and the first element in the second array (y-array) as the 
y-coordinate, for example: 


MAT GRAPH LINES x_array, y_array 


The coordinates are taken,,one from each array, in sequence. Notice that 
you only specify the name of the array; you do not specify the array 
elements, nor do you specify the whole array with parentheses. Virtual 
arrays and packed decimal arrays are invalid. 


The following example displays a circle on the terminal screen using the 
MAT GRAPH LINES statement. 


Example 


OPTION TYPE = EXPLICIT 
DECLARE SINGLE CONSTANT radius = 0.4 
DECLARE LONG CONSTANT npoints = 40 
DECLARE SINGLE increment, & 
x,y, turn, & 
LONG Counter 
DIM SINGLE x_array(npoints), y_array(npoints) 
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increment = 2 * PI/npoints 
turn = 0 
'+ 
'Fill the arrays 
i- 
FOR Counter = 0% TO npoints 
x = COS(turn) * radius 
y = SIN(turn) * radius 
t+ 
!Adjust points for center of 0.5,0.5 
!- 
x_array(Counter) = x + 0.5 
y_array(Counter) = y + 0.5 
turn = turn + increment 
NEXT Counter 
I+ 
!Draw the lines connecting each point 
I- 
MAT GRAPH LINES x_array, y_array 
END 


Output 


See eee ee ee 


2K-5525-86 


The MAT GRAPH LINES statement in the circle example can be replaced 
with a MAT GRAPH POINTS statement to display a circle of points. 
Alternatively, a MAT GRAPH AREA statement in this example would 
produce a solid circle. 
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The following program illustrates the use of the COUNT clause in a MAT 
GRAPH LINES statement. The COUNT clause allows you to terminate 
the display after the specified number of points has been processed, 
ignoring any remaining array elements. In the example only half of the 
points in the circle are specified by the index in the COUNT clause. There 
are actually 41 points in the circle; the MAT GRAPH LINES statement 
connects the first 21 points from the arrays and displays a semicircle. 


Example 


FOR Counter = 0% TO npoints 
x = COS(turn) * radius 
y = SIN(turn) * radius 
x_array(Counter) = x + 0.5 
y_array(Counter) = y + 0.5 
turn = turn + increment 
NEXT Counter 
!+ : 
!Draw the lines connecting the first half of the points 
! 
MAT GRAPH LINES , COUNT (npoints/2 + 1) : x_array, y_array 
END 


Output 


aa eee eee 


2K-5524-86 


Points are frequently less structured than those created by the circle 
program. Statistics from surveys, for example, could provide the data 
for a line chart. The following program plots the data gathered from an 
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informal survey of supermarket employees and uses DATA and READ 
statements to fill the coordinate arrays. When data is maintained in a file, 
you can open the file in the usual manner within your graphics program. 
The employees’ salaries (divided by 100,000) provide the data for the 
x-array. Employees rated their job satisfaction on a scale of 0 to 1; this 
provides the data for the y-array. The DATA statement provides the salar 
and work satisfaction rating for each of the fifteen employees surveyed. 
The chart illustrates the relationship between salary earned and employee 
job satisfaction. 


Example 


OPTION TYPE = EXPLICIT 
DECLARE LONG Counter 
DIM SINGLE x_array (14) ,y_array(14) 


t+ 

!Draw the axes 

! 

GRAPH LINES 0.225,1.0; 0.225,0.2; 1.0,0.2 
1+ 

{Read in the data 

!- 


DATA 0.43,0.5, 0.475,0.6, 0.5,0.4, 0.55,0.5, & 
0.575,0.55, 0.585,0.5, 0.6,0.475, 0.625,0.575, & 
0.65,0.575, 0.8,0.7, 0.825,0.575, 0.9,0.8, & 


0.925,0.825, 0.95,0.85, 1.0,0.95 
READ x_array(Counter), y_array(Counter) FOR Counter = 0% TO 14% 
t+ 
!Draw the lines 
t- 


MAT GRAPH LINES x_array, y_array 
{+ 


!Add the text 

t- 

GRAPH TEXT AT 0.225,0.165 : "5 | 10] 15 1 201 26 | 301 35 |" 
GRAPH TEXT AT 0.3,0.1 : "Salary in thousands of $" 

GRAPH TEXT AT 0.05,0.7 : "Work" 

GRAPH TEXT AT 0.05,0.625 : "Satis-" 

GRAPH TEXT AT 0.05,0.575 : "faction" 

END 
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Output 





he 1k k 


Satis- 
faction 





Gio ot ght eh: ht Jo: gs: 


Salary in thougands of ¢ 


I 


ZK-4868-85 


Chapter 4 illustrates how to change the text attributes such as the justifi- 
cation and text path so that graphs can be accurately labeled. 


'.8 Graphics Subprograms 


Graphics images can be defined in separate blocks of code known as 
pictures. A picture can be compiled separately and must be delimited by a 
PICTURE and an END PICTURE statement, for example: 


PICTURE unique_name 


END PICTURE 


As with other subprograms, pictures should be declared with an 
EXTERNAL statement in the main program. To invoke a picture, you 
use the DRAW statement, not the CALL statement, for example: 


PROGRAM display 


EXTERNAL PICTURE sample 
DRAW sample 
END PROGRAM 
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You can pass parameters to pictures as with any other subprogram. The 
following example invokes the picture triangle several times with the 
DRAW statement. The coordinates of the third point for the triangle are 
passed as parameters with each invocation of the picture. 


PROGRAM display 
EXTERNAL PICTURE triangle(SINGLE, SINGLE) 


DRAW triangle(0.2,0.8) 

DRAW triangle(0.5,0.9) 

DRAW triangle(0.8,0.8) 

DRAW triangle(0.8,0.2) 

DRAW triangle(0.5,0.1) 

DRAW triangle(0.2,0.2) 
END PROGRAM 


PICTURE triangle (SINGLE x,y) 
GRAPH LINES 0.4,0.5; 0.6,0.5; x,y; 0.4,0.5 
END PICTURE 


Output 


(oN 


a 


ZK-5506-86 


The DRAW statement can include several useful options to invoke pictures 
in a variety of ways. Chapter 6 discusses pictures in detail and illustrates 
how to create complex images with the DRAW statement. Simple pictures 
are used where appropriate in Chapters 3 through 5. 
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§ Summary 


This chapter has explained how to use the following statements: 


GRAPH POINTS 
GRAPH LINES 
GRAPH AREA 
GRAPH TEXT 

PLOT LINES 

MAT GRAPH POINTS 
MAT GRAPH LINES 
MAT GRAPH AREA 


This chapter has also introduced pictures and how to invoke them with 


the 


DRAW statement. These concepts are illustrated throughout the 


manual and expanded fully in Chapter 6. 


The points, lines, areas, and text in this chapter all display the VAX BASIC 
default attributes. VAX BASIC provides many statements to change 
attributes from their default values. The following chapters show you how 
to enhance your graphics displays by changing these attributes. 
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Chapter 3 


Changing the Appearance of Graphics 
Objects 


You can control the exact appearance of points, lines, and areas by setting 
attribute values. This chapter shows you how to change the color, size, 
and style of these graphics objects. For each graphics object, this chapter 
does the following: 


e Illustrates the available attribute values 

e Demonstrates how to select the attributes 

e Shows how to ask about the attribute values 

e Provides a table of available attributes and their values 


Text attributes are discussed separately in Chapter 4. 


1 Graphics Attributes 


The examples in Chapter 2 illustrate the default values for the attributes of 
each graphics object displayed. You can change these attributes with SET 
statements, and you can inquire what the current values are with ASK 
statements. The default attributes are displayed unless you have supplied 
alternative values with a SET statement. Table 3-1 shows the attributes 
you can select for each of the graphics objects. Note that SET statements 
can be used in immediate mode in the environment if SET is preceded 
with a backslash (\). 
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Table 3-1: Graphics Objects and Their Attributes 


Graphics Object Attributes 

Point Style, color, and size of the marker 
Line Style, color, and width of the line 
Area Interior fill styles, and color of the fill 


All attributes are not necessarily supported by each hardware device. Fo 
the most part, this chapter shows examples of the available attributes for 
VT125 and VT240 terminals. 


3.2 Setting the Color 


The colors red, green, and blue are available by default on your color 
monitor in addition to the background color. You can display these 
four colors on your screen at the same time. Some devices, such as the 
VAXstation II/GPX, are more versatile; the examples in this section show 
output displayed on a VT240 terminal. 


Many factors affect the display and perception of foreground colors; the 

colors displayed in this manual may not be the same as those displayed 
on the device you use. The brightness and contrast controls change the 

perceived color, as do the available room light and any previously define 
terminal color setup. Note that if you have a monochrome monitor, the 
color statements may affect the shading of graphics objects displayed on 
your screen. 


Each color has a numeric index value associated with it. Table 3-2 lists 
the default color associated with each color index for VT125 and VT240 
terminals. Color 0 represents the background color, or the color of a 
display surface that is clear. Colors 1, 2, and 3 represent foreground 
colors. If you have a color terminal, make sure that you assign the correc 
device type number to GKS$WSTYPE, as described in Chapter 1. You 
may have to reset your terminal color setup after executing a graphics 


program. 
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Table 3-2: Default Colors for VT125 and VT240 Color 


Terminals 
Index Color 
0 Black 
1 Green 
2 Red 
3 Blue 


You use these numeric values to change the colors in your displays. 


».1 Changing the Color Index 


When you supply a numeric value to one of the SET . .. COLOR state- 
ments, the value is used to determine the color of any subsequent points, 
lines, filled areas, or text. For instance, each of the following statements 
sets the color of the objects specified to blue. 


SET POINT COLOR 3 
SET LINE COLOR 3 
SET AREA COLOR 3 
SET TEXT COLOR 3 


You can set the color before executing a graphics output statement. The 
color you set continues to be the foreground color for that graphics object 
until you change it with another SET ... COLOR statement. (Note that 
if you set the foreground color to the same color as the background, you 
will not be able to distinguish the display from the background.) The 
following example sets the color for the lines, area, and text in a simple 
diagram. 
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Example 


t+ 
{Outline the book 
to 


SET LINE COLOR 


1 
GRAPH LINES 0.26,0.8; 0.43,0.8; 0.43,0.25; 0.26,0.25; 0.26,0.8; & 
0.35,0.88; 0.48,0.88; 0.48,0.33; 0.43,0.25 & 
GRAPH LINES 0.43,0.8; 0.48,0.88 
1+ 
!'Fill spine 


SET AREA COLOR 3 
GRAPH AREA: 0.43,0.8; 0.43,0.25; 0.48,0.33; 0.48,0.88 


SET TEXT COLOR 2 

GRAPH TEXT AT 0.265,0.65 : "Your" 
GRAPH TEXT AT 0.26,0.6 : "BASIC" 

GRAPH TEXT AT 0.265,0.55 : "book" 


Output 


aa tame: * 





————— 


The design displayed by the following example is achieved with a SET 
LINE COLOR statement inside a loop to vary the color. The program 
connects points on the perimeter of an oval. 
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Example 


OPTION TYPE = EXPLICIT 

OPTION ANGLE = RADIANS 

DECLARE LONG loop_count, inner, 
loop_index, counter, 
color_no, 

SINGLE turn 
DIM SINGLE x_array(40),y_array(40), & 
x2_array(1) ,y2_array(1) 


& & & 


turn = 0 
t+ 
!'Fill arrays with coordinates for points on perimeter 
t- 
FOR loop_count = 0 TO 40 
turn = 2 * PI * loop_count/40 
x_array(loop_count) = (SIN(turn) + 1)/2 


y_array(loop_count) = (COS(turn) + 1)/4 

NEXT loop_count 

t+ 

!Draw the perimeter 

t- 

MAT GRAPH LINES x_array, y_array 

color_no = 1 

1+ 

{Select points on perimeter 

t- » 

FOR loop_index = 0 TO 40 STEP 4 
x2_array(counter) = x_array(loop_index) 
y2_array(counter) = y_array(loop_index) 
I+ 
!Inner loop to connect other points to 
'the point x2_array (counter) ,y2_array (counter) 
f- 
counter = counter + 1 
FOR inner = 0 TO 40 STEP 4 

x2_array(counter) = x_array (inner) 
y2_array(counter) = y_array (inner) 
t+ 
!Keep the color 1, 2, or 3 
{- 
IF color_no = 4 
THEN color_no = 1 
END IF 
SET LINE COLOR color_no 
color_no = color_no + 1 
t+ 


!Draw all the lines connecting selected point to others 
!- 
MAT GRAPH LINES x2_array, y2_array 
NEXT inner 
NEXT loop_index 
END 
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Output 


=a 


3.2.2 Changing the Color Intensities 





The four index colors are each defined by the intensities of red, green, an 
blue. The default intensity values for the color indices are as follows: 


Color 
Index 


0 


1 
2 
3 


Color 
Black 
Green 
Red 
Blue 


Red 
Intensity 


0.0 
0.0 
1.0 
0.0 


Green 
Intensity 


0.0 
1.0 
0.0 
0.0 


Blue 
Intensity 


0.0 
0.0 
0.0 
1.0 


You can change the actual color displayed for each index by changing 
the red, green, and blue intensities with the SET COLOR MIX statement. 
When you use this statement, you alter the default color of the index 
displayed on your screen. For instance, although the color index 3 display 
blue by default, you can change the color that this index displays by 
changing the intensity values for red, green, and blue while index 3 is 
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selected. By supplying alternative values for the intensities, you can 
greatly increase your choice of possible foreground colors. (The device 
you use may not have the capability to display more than four of these 
at the same time.) The values for these intensities can vary from 0 
through 1. 


The following statement changes the color index 3 to be raspberry instead 
of the default blue. 


Example 


DECLARE SINGLE red_var, green_var, blue_var 

red_var = 0.84 

green_var = 0.0 

blue_var = 0.56 

SET COLOR MIX , INDEX 3 : red_var, green_var, blue_var 


Remember that color index values are device dependent. Values for VT125 
and VT240 terminals and for VAXstations can be found in Appendix B in 
this manual. Values for other devices can be found in the VAX GKS 
documentation and in the documentation for the particular device you 
use. 


The following program illustrates the use of the SET COLOR MIX state- 
ment. Each time the graphics object (a wheel) is drawn, the color index is 
set to 2; however, the default color of red is changed. Instead, the values 
of the color intensities are changed for each display of the wheel, and in 
each case the diagram is presented with a changed color. Only one screen 
is illustrated after the example. 


Example 


OPTION TYPE = EXPLICIT 

EXTERNAL PICTURE Wheel 

DECLARE SINGLE green, blue, red 

f+ 

‘Set up the variations in color intensities 
SET LINE COLOR 2 

red = 0.0 

green = 0.0 

blue = 0.56 

14 

!Set index 2 to a violet shade 

1- 

SET COLOR MIX , INDEX 2 : red, green, blue 
DRAW Wheel 

SLEEP 5% 

CLEAR 
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1+ 

!Set up index 2 as orange 
t- 

red = 0.8538 

green = 0.6646 

blue = 0.2862 


SET COLOR MIX , INDEX 2 : red, green, blue 


DRAW Wheel 
END 


PICTURE Wheel 


DECLARE SINGLE loop_count, loop_index, 
turn,x_center, y_center,x,y 
DIM SINGLE x_array(40) ,y_array (40) 
1+ 
!'Fill the arrays and draw the circle 
f= 
turn = 0 
FOR loop_count = 0 TO 40 
turn = 2 * PI * loop_count/40 
x_array(loop_count) = (SIN(turn) + 1)/2 
y_array(loop_count) = (COS(turn) + 1)/2 
NEXT loop_count 
MAT GRAPH LINES x_array, y_array 
Draw_spokes: 
t+ 
{Select 8 points on circle for spokes 
t- 
FOR loop_index = 5 TO 40 STEP 5 
x = x_array(loop_index) 
y = y_array(loop_index) 
x_center = 0.5 
y.center = 0.5 
GRAPH LINES x,y ; x .center,y_center 
NEXT loop_index 
END PICTURE 
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Output 





The following example illustrates many of the possible shades that you 
can display on your terminal. The wheel is drawn within a set of three 
loops that change the intensities of red, green, and blue for the current 
color index. Some of the colors are close to the background color; there- 
fore, if you run this program, you should turn up the brightness on your 
terminal. (Be aware that this program runs for several minutes.) 
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Example 


DECLARE SINGLE green, blue, red 
EXTERNAL PICTURE wheel 
color_var = 1 

t+ 


'Set up the variations in color intensities 
{- 
FOR green = 0.2 TO 1 STEP 0.2 
FOR red = 0.2 TO 1 STEP 0.2 
FOR blue = 0.2 TO 1 STEP 0.2 
SET COLOR MIX , INDEX color_var : red, green, blue 


SET LINE COLOR color_var 
'+ 


!For every iteration of this loop draw the wheel 
1- 


DRAW wheel 
SLEEP 2% 
CLEAR 
NEXT blue 
NEXT red 
NEXT green 
END 


Remember that if you do not change the values for the intensities, the 
index values display the default index colors. 


3.2.3 Asking About Color Attributes 


ASK statements allow you to retrieve the current value of attributes. 
VAX BASIC provides two ASK statements that allow you to retrieve the 
information about the color attributes. 


The ASK MAX COLOR statement allows you to retrieve the highest 
valid color index value for the particular device you use. In the following 
statement, the highest color index number available for that device is 
assigned to the variable highest _poss. 


ASK MAX COLOR highest_poss 


For instance, if the value returned is 10, this means that the highest 
index value you can set is 10. This does not necessarily mean that there 
are 10 different indices on the device you are using because the color 
indices need not be contiguous. (VAX BASIC signals a warning when you 
open a device that does not have contiguous color indices.) Consult the 
documentation for your particular device for details. 


3-10 Changing the Appearance of Graphics Objects 


The ASK COLOR MIX statement retrieves the current values for the 
intensities of red, green, and blue, in that order, for the particular color 
index that you specify. The following statement asks for the current 
intensities for red, green, and blue when the color index is set to 2. The 
values for the intensities are placed in the three variables you supply. The 
assigned values are the defaults unless a SET COLOR MIX statement has 
been executed. 


ASK COLOR MIX , INDEX 2 : red_var, green_var, blue_var 


.3 Setting Point Attributes 


In addition to changing the color of points, you can change the style and 
the size. When you display a point with the default attributes, the point is 
an asterisk (*) of the smallest possible size your device can display. 


3.1 Changing t's Point Style 


So far the examples have displayed an asterisk to mark a point on the 
screen. As shown in Table 3-3, VAX BASIC provides five point markers, 
each with a numeric value. At the start of program execution, the point 
style value is 3. The number of available marker styles varies according to 
the device you use. 


Table 3-3: Point Styles 
Value Point Style 


1 Dot 

2 Plus sign 

3 Asterisk (default) 
4 Circle 

5 Diagonal cross 


To display a point style other than the default, you use the SET POINT 
STYLE statement. You must supply a numeric value for the point style 
you want. For example, the following statements set the point style to be 
a plus sign and a dot respectively: 


SET POINT STYLE 2 
SET POINT STYLE 1 
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To change the point style, the SET POINT STYLE statement must preced 
the output statement that displays the points. The point style you set 
remains in effect until VAX BASIC executes another SET POINT STYLE 
statement. To regain the default point style, you must set the point style 
back to the value 3 for the asterisk. 


Example 


PROGRAM point_styles 
1+ 
!'Set the style to a dot 
t- 
SET POINT STYLE 1 
GRAPH POINTS 0.1,0.2; 0.15,0.2 
{+ 
!'Set the style to a plus sign 
t- 
SET POINT STYLE 2 
GRAPH POINTS 0.2,0.2; 0.25,0.2 
I+ 
!Set the style to an asterisk 
{- 
SET POINT STYLE 3 
GRAPH POINTS 0.3,0.2; 0.35,0.2 
t+ 
!Set the style to a circle 
{- 
SET POINT STYLE 4 
GRAPH POINTS 0.4,0.2; 0.45,0.2 
I+ 
!Set the style to a diagonal cross 
1- 
SET POINT STYLE 5 
GRAPH POINTS 0.5,0.2; 0.55,0.2 
END PROGRAM 


3-12 Changing the Appearance of Graphics Objects 


Output 


: ope ROO KX 


a ee 


ZK-4904-86 


3.2 Changing the Point Size 


You can increase the size of each point style except the dot. To do this, 
supply the SET POINT SIZE statement with a numeric value for the 
scale of the marker. Possible point size values depend on the device. For 
example, valid values for VT125 and VT240 terminals are 1 (the default) 
through 12. The new point size remains in effect until another SET 
POINT SIZE statement is executed. Note that the dot is always displayed 
in the smallest possible size, size 1. The following example shows a few 
of the point sizes available on VT240 terminals. 


Example 


DECLARE LONG loop_count 

FOR loop_count = 1 TO 5 
SET POINT STYLE loop_count 
SET POINT SIZE loop_count 
GRAPH POINTS loop_count/5,0.3 

NEXT loop_count 

END 
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Output 


+¥OX 


vey ee Ee | 


ZK-4896-86 


The following example marks each of the vertices of a hexagon with a 


size 1 diagonal cross and then marks the same points with size 7 circle 
markers. 


Example 


OPTION TYPE = EXPLICIT 

DECLARE SINGLE x,y, & 
LONG loop 

i+ 

!Supply data for points of hexagon 

1- 

DATA 0.7,0.5, 0.6,0.3, 0.4,0.3, & 

0.3,0.5, 0.4,0.7, 0.6,0.7 
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1+ 
!'Procedure for each point 
t- 
FOR loop = 0 TO 5 
READ x,y 
t+ 
!Draw a size 1 diagonal cross at x,y 
{- 
SET POINT STYLE 5 
SET POINT SIZE 1 
SET POINT COLOR 2 
GRAPH POINTS x,y 
I+ 
!Draw a size 7 circle marker at x,y 
t- 
SET POINT STYLE 4 
SET POINT SIZE 7 
SET POINT COLOR 3 
GRAPH POINTS x,y 
NEXT loop 
END 


Output 
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3.3.3 Asking About Point Attributes 


You can retrieve information about the point style and color by supply- 
ing integer variables with the ASK POINT statements. The following 
statements retrieve the values for the point style and color respectively. 


ASK POINT STYLE style_var 
ASK POINT COLOR color_var 


The values are returned in the variables you supply. For instance, after the 
ASK POINT STYLE statement in the following example is executed, the 
current style value is stored in the variable style_var. The value returned 
is the value used if an appropriate output statement were to be executed a 
this time. This feature allows you to store attribute values, change them, 
and reset them to the stored values at another point in your program. 


Example 


DECLARE LONG style_var, color_var 

EXTERNAL PICTURE Multi_points (LONG, LONG) 

GRAPH POINTS 0.1,0.85; 0.2,0.85; 0.3,0.85; 0.4,0.85 
t+ 

!Ask for the value of the point style and color 

t- 

ASK POINT STYLE style_var 

ASK POINT COLOR color_var 

SET POINT STYLE 4 

SET POINT COLOR 3 


1+ 


!Invoke a picture using the new values 
t- 


DRAW Multi_points(style_var, color_var) 
1+ 


'Reset the attributes to the stored values 
f- 


SET POINT STYLE style_var 
SET POINT COLOR color_var 


For more information about pictures, see Chapter 6. 


The ASK MAX POINT SIZE statement allows you to retrieve the largest 
possible value for the point size for your particular device. This value is 
stored in a variable you supply. The example shows the largest value used 
in a loop to draw concentric circles using point style 4. 
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Example 


DECLARE LONG maximun,loop_counter 

ASK MAX POINT SIZE maximnun 

SET POINT STYLE 4 

FOR loop_counter = 1 TO maxinum 
SET POINT SIZE loop_counter 
GRAPH POINTS 0.5,0.5 

NEXT loop_counter 

END 


Output 


(OO 





ee a ee 


ZK-§507-86 


3.4 Setting Line Attributes 


As with points, you can change the style, size, and color of lines. The 
effects of these changes vary depending on the type of device you use. 
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3.4.1 Changing the Line Style 


VAX BASIC provides the four different line styles described in Table 3-4. 
At the start of program execution, the line style is value 1, solid. 


Table 3-4: Line Styles 
Value Line Style 


1 Solid (default) 
2 Dashed 

3 Dotted 

4 Dashed-dotted 


To change the line style, supply the selected value to the SET LINE STYLE 
statement. This example displays each of the four line styles. 


Example 


DECLARE LONG loop_count, & 
SINGLE y 
FOR loop_count = i TO 4 
SET LINE STYLE loop_count 
y = loop_count/10 
GRAPH TEXT AT 0.1,(y + 0.05) : "This is line style " + STR$(loop_count) 
GRAPH LINES 0.1,y; 0.45,y 
NEXT loop_count 
END 
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Output 


This is line style 4 


This is line style 1 


ee er 


ZK-4905-86 


4.2 Changing the Line Width 


You can increase the width of lines just as you can increase the size of 
points. To do this, use the SET LINE SIZE statement. 


The output of the following example shows a solid line increased to sizes 
10, 20, and 60 respectively. When the line width is increased to a large 
size, the outer edges of closed figures no longer meet, as is the case when 
the hexagon lines are increased to size 60. Open figures can be increased 
without this apparent distortion. The amount of distortion that large sizes 
produce depends on the capabilities of your terminal. 
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Example 


EXTERNAL PICTURE Hexagon (LONG) 
DRAW Hexagon(10) 

SLEEP 5% 

CLEAR 

DRAW Hexagon (20) 

SLEEP 5% 

CLEAR 

DRAW Hexagon (60) 

END 


PICTURE Hexagon(LONG line_size) 
OPTION TYPE = EXPLICIT 
DECLARE SINGLE x_array(6) ,y_array (6) 
DECLARE LONG loop 
DATA 0.7,0.5, 0.6,0.3, 0.4,0.3, & 
0.3,0.5, 0.4,0.7, 0.6,0.7, 0.7,0.5 
READ x_array(loop),y_array(loop) FOR loop = 0 TO 6 
SET LINE SIZE line_size 
MAT GRAPH LINES x_array, y_array 
END PICTURE 


Output Screen 1: 





ZK-4899-86 
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Output Screen 2: 





2K-4898-86 


Output Screen 3: 





Z2K-4897-86 
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By changing both the line size and the line style, you can achieve some 
interesting results. Here, the line size is 10 and the line style is value 4, 
dashed-dotted. 


Example 


OPTION TYPE = EXPLICIT 
EXTERNAL PICTURE Hexagon(LONG) 
SET LINE STYLE 4 

DRAW Hexagon (10) 

END 


Output 


ZK-4906-86 


3.4.3 Asking About Line Attributes 
You can retrieve the value of the current line style with the ASK LINE 


STYLE statement. Here, GRAPH LINES draws a line with the style value 
stored previously in the variable style_value. 
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ASK LINE STYLE style_value 
SET LINE STYLE 3 


SET LINE STYLE style_value 
GRAPH LINES 0.5,0.8; 0.2,0.4; 0.3,0.3 


You can also retrieve the current line color with the ASK LINE COLOR 
statement. 


Example 


DECLARE LONG which_color 
ASK LINE COLOR which_color 
IF which_color = 1 
THEN 
SET LINE COLOR 3 
ELSE 
SET LINE COLOR 2 
END IF 


The largest possible line size for your device can be retrieved with the 
ASK MAX LINE SIZE statement. You must supply a numeric variable. 


ASK MAX LINE SIZE thickest 


5 Setting Area Attributes 


Areas can be represented by four different interior fill styles. Two of 
the interior fill styles, pattern and hatch, can produce a wide variety of 
representations of an area. To make these changes, you use the SET 
AREA STYLE and the SET AREA STYLE INDEX statements. 
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3.5.1 Changing the Fill Style 


VAX BASIC provides four different interior fill styles for areas: 
e SOLID (the default) 


¢ HOLLOW 
e PATTERN 
e HATCH 


At the start of program execution, the interior fill style is solid. 


Unlike other attributes, the interior fill styles do not have numerical 
values. Instead, you supply the SET AREA STYLE statement with a strir 
expression equivalent to one of the interior fill style names. You can 
enter strings in either upper- or lowercase. Both of the SET AREA STYL 
statements in the following example set the interior fill style to hollow. 


Example 
DECLARE STRING CONSTANT hollow_fill = "HOLLOW" 


SET AREA STYLE hollow_fill 

MAT GRAPH AREA x_array, y_array 
SET AREA STYLE "hollow" 

MAT GRAPH AREA x_array, y_array 


The following example displays each of the four interior fill styles. As 
the pattern style mixes only colors, the difference between the solid and 
pattern styles may not be discernible on a monochrome display. 


SET AREA STYLE "Hollow" 
GRAPH AREA 0.0,0.5; 0.1,0.5; 0.1,0.0; 0.0,0.0 


SET AREA STYLE "Solid" 
GRAPH AREA 0.2,0.5; 0.3,0.5; 0.3,0.0; 0.2,0.0 


SET AREA STYLE "Pattern" 

GRAPH AREA 0.4,0.5; 0.5,0.5; 0.5,0.0; 0.4,0.0 
SET AREA STYLE "Hatch" 

GRAPH AREA 0.6,0.5; 0.7,0.5; 0.7,0.0; 0.6,0.0 
END 
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Output 


hs 





5.2 Changing Pattern and Hatch Styles 


The interior fill styles for pattern and hatch can be changed with the SET 
AREA STYLE INDEX statement. The pattern or hatch style displayed 
depends on the setting of the area style index. Table 3-5 lists the various 
styles you can display by changing the index. 
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Table 3—5: VT125 and VT240 Pattern and Hatch Style Inde: 


Values 
Fill Style Index Value Display 
HATCH 1 (default) Cross hatched 
2 Hatching with lines at 45 degrees 
3 Hatching with lines at -45 degrees 
4 Hatching with horizontal lines 
> Hatching with vertical lines 
6 Hatching with lines at 45 degrees 
(sparse) 
7 Hatching with lines at -45 degrees 
(sparse) 
8 Hatching with horizontal lines (sparse) 
9 Hatching with vertical lines (sparse) 
10-19 Varying density hatches! 
33-126 Hatching with ASCII character” 
PATTERN? 1 (default) Mixes colors 1 and 2 
2 Mixes colors 2 and 3 
3 Mixes colors 3 and 1 
4 Mixes colors 0 and 1 
5 Mixes colors 0 and 2 
6 Mixes colors 0 and 3 





1, varying density hatch style is a mixture of pixels of a given color and white pixels, which gives 
the appearance of different shades. For hatch styles 10 through 19, the hatches progress from lighte 
to darker; 10 being the lightest and 19 being. the darkest. 


>The style index values 33 through 126 generate hatching with the corresponding character from thi 
ASCII table. For example, the ASCII value for the character A is 65; a hatched fill area with style 
index 65 fills the area with a number of uppercase As. 


3 Pattern style index values are appropriate only for color monitors. 


The default style index value is 1 for both hatch and pattern. Samples of 
the default pattern and hatch fill styles are shown in Section 3.5.1. The 

available fill styles for pattern and hatch vary according to the device you 
use; Appendix B lists the styles available for VAXstations. The following 
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example displays three of the many hatch styles available on VT125 and 
VT240 terminals. 


Example 


EXTERNAL PICTURE Draw_hatch (LONG) 
SET AREA STYLE "HATCH" 

DRAW Draw_hatch(3) 

SLEEP 3% 

CLEAR 

DRAW Draw_hatch(65) 

SLEEP 3% 

CLEAR 

DRAW Draw_hatch(72) 

END 


PICTURE Draw_hatch(LONG style_index) 
OPTION TYPE = EXPLICIT 
DECLARE SINGLE x_array(5),y_array(5) 
DECLARE LONG loop 
DATA 0.7,0.5, 0.6,0.3, 0.4,0.3, & 
0.3,0.5, 0.4,0.7, 0.6,0.7 
READ x_array(loop),y_array(loop) FOR loop = 0 TO 5 
SET AREA STYLE INDEX style_index 
MAT GRAPH AREA x_array, y_array 
END PICTURE 


Output Screen 1: 





ZK-4902-86 
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Output Screen 2: 


Z2K-4901-86 


Output Screen 3: 


———e—e—e—e—————— 


HHHHHHHHHHHHE 
HHHHHHHHHHHHHHt 
HHHHHHHHHHHHHHHHE 
THHHHHHHHHHHHHHEHHHE 
~{HHHHHHHHHHHHHHEHHHHt 
JHHHHHHHEHHHHHHHHHHHHHH} 
AHHHHAHHHHHERHHHHHRH HE 
4HHHEHHHHHHHHHHHHHH HH 
4HHHHHHHHHHHEHHHHHH 
4HHHEHHHHHHHHHHHt 
AHHHHHHHEHHHHHH! 
{HHHHHHHHHHHH 


ot 


2K-4900-86 
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5.3 Asking About Area Attributes 


The ASK AREA STYLE statement lets you retrieve the value of the current 
style. This value is placed in a string variable you supply. 


Example 
DECLARE STRING which_style 


ASK AREA STYLE which_style 
GRAPH TEXT AT 0.1,0.5 : "The interior fill style is " + which_style 


Similarly, the ASK AREA STYLE INDEX statement retrieves the current 
index value of the pattern or hatch style. You can use this value to reset 
the index after branching to another program module, as shown in the 
following example. The example also stores the initial area color and fill 
style. You must supply variables of the appropriate data type with each of 
these statements. 


Example 


PROGRAM Welcome 
EXTERNAL PICTURE Menu_setup 
DECLARE LONG index_number, which_color 
DECLARE STRING fill 
ASK AREA STYLE fill 
ASK AREA STYLE INDEX index_number 
ASK AREA COLOR which_color 
+ 
!Branch to another module 
1- 
DRAW Menu_setup 


I+ 

!Return to main program, reset the area attributes 
te 

SET AREA STYLE fill 

SET AREA STYLE INDEX index_number 

SET AREA COLOR which_color 


END PROGRAM 
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3.6 Summary 


This chapter has explained how to use the following statements: 


e SET/ASK ... COLOR 

e SET/ASK COLOR MIX 

e SET/ASK ... STYLE 

e SET... SIZE and ASK MAX... SIZE 

These statements allow you to set and inquire about the color, size, and 


style attributes of points, lines, and areas. The following chapter shows 
you how to change the attributes associated with graphics text. 
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Chapter 4 


Changing Text Attributes 


You can change the direction, height, width, spacing, angle, and justifi- 
cation of characters in different font designs. This chapter illustrates the 
many text attributes that you can access with VAX BASIC statements. 


1 Selecting a Font 


VAX BASIC supports both hardware and software fonts. The number 

of available hardware fonts depends on the device you use. VAXstations 
support several hardware fonts, while VT125 and VT240 terminals support 
one hardware font each. If no hardware fonts are available for a device, 
software fonts are used by default. For illustrations of the VAXstation 
hardware fonts, see Appendix B. In general, hardware fonts are displayed 
faster than software fonts. 


Software fonts provide a graphical representation of defined characters. 
A font can be defined as a complete set of monospaced or proportionally 
spaced characters of a particular printing type, size, and face. 


The fonts displayed in this chapter are the fonts that are available on 
VT125 and VT240 terminals. These fonts are proportionally spaced and 
are known as the Hershey fonts, digitized by A.V. Hershey of the Naval 
Surface Weapons Laboratory. The default font and the Hershey fonts are 
illustrated in Figure 4-1. The values representing the fonts are -1 through 
-23, as illustrated. The default font is software font number -1. 
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Figure 4-1: VAX BASIC Software Fonts 


Font No. 1 


FOEYT NO, -2 
Font No, —3 
Zofu =o. -—4 
rent tle, —2 
Font No. —6 
Zokev Zo. —7 
Font No, -8 
Font No. -—9 
Zofy Zo. -10 
Font No, -1f 
Font No, -12 


Font No. —13 
Eouy Ho. -14 
Font No, -15 
Font No. -16 
Gont No. -17 
Font Ho, -18 
Pont Deo. <1 
ve<( >>fl pfu 


Bove Ker Bs 


i ir 
= \v( Ta Jute pe 


IL 


Oe eee 
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Note that none of the statements discussed in this chapter has any effect 
on output from the VAX BASIC statements PRINT and PRINT USING. 
In graphics programs, it is recommended that you use GRAPH TEXT 
statements, not PRINT statements. 


You can access the different fonts easily with the SET TEXT FONT 
statement. This statement requires a number for the font you want to us¢ 
In addition, you can optionally specify a string expression representing 
the degree of precision with which you want the characters drawn. The 
following example displays sample characters from the hardware font 
and two of the software fonts available on VT125 and VT240 terminals. 
Depending on the device you use, the hardware font may be displayed 


faster. 
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Example 


SET TEXT FONT -1, "CHAR" 

GRAPH TEXT AT 0.0,0.7 : "This is hardware font -i" 
SET TEXT FONT -8 , "STROKE" 

GRAPH TEXT AT 0.1,0.5 : "This is software font -8" 
SET TEXT FONT -12 , "STROKE" 

GRAPH TEXT AT 0.1,0.3 : "This is software font -12" 


Output 


This is hardware font -1 
This is software font -8 


This Is software font -12 


I ee 


ZK-5510-86 


There are three possible values for the precision string: 


e STRING 
¢ CHAR 
e STROKE (the default) 


String precision provides the least degree of accuracy, while stroke pro- 
vides the most. 


Software fonts can be drawn only with stroke precision. If you request a 

software font and do not specify a precision string, VAX BASIC uses stroke 
precision by default. Stroke precision displays text characters as accurately 
as possible according to the specifications in the font design. Such features 
as the text height and the way text is clipped are affected by the precision. 
Attributes such as height, spacing, and the expansion factor are accurate 

for stroke precision. Software fonts are always drawn accurately regardless 
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of the device; the accuracy with which hardware fonts are drawn is devic 
dependent. 


You can supply one of two possible values for the precision string when 
you specify a hardware font: STRING and CHAR. Hardware fonts cannc 
be drawn with stroke precision; if you specify stroke precision for a 
hardware font, VAX BASIC displays the software font with the number 
that is closest to the font you specified. 


The most significant trade-off between hardware and software fonts is 
speed; hardware fonts can be much faster than precise software fonts. 
If you want a faster display of characters, you should specify CHAR 
precision with the following statement: 


SET TEXT FONT 1, "CHAR" 


Character precision clips the text after the last complete character, while 
stroke precision clips the text exactly at the edge of the boundary of 

the display area, mid-character if necessary. With string precision, text 
is clipped either by character or by stroke precision depending on the 
capabilities of the device you use. The effect of each of these precision 
values may not be discernible in all cases, as the precision of text clippings 
depends on the capabilities of the device you use. Clipping is discussed 
fully in Chapter 5. 


The following example illustrates the effect of the precision value on the 
clipping of the text: 
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Example 


SET TEXT HEIGHT 0.05 
I+ 
{Select the hardware font for STRING precision 
1- 
SET TEXT FONT -1 , "STRING" 
GRAPH TEXT AT 0.05,0.6 : 
"Clipping for STRING precision varies with each device" 
I+ 
{Select the hardware font with CHAR precision 
tS 
SET TEXT FONT -1 , "CHAR" 
GRAPH TEXT AT 0.05,0.5 : 
"CHARACTER precision clips text after complete characters" 
'+ 
{Select software font -3 with STROKE precision 
t- 
SET TEXT FONT -3 , "STROKE" 
GRAPH TEXT AT 0.05,0.4 : 
"STROKE precision clips text mid-character if necessary" 


Output 


(CS 


Glipping for STRING 
CHARACTER precision 


STROKE precision clips text mid—charac 


Se ee ee eee: 


2K-5509-86 


Note that if you request a software font with character or string precision, 
VAX BASIC displays the text with the hardware font that is closest in 
number to the font you requested. Similarly, if you request a software 
font that the device does not support, VAX BASIC displays the text with 
the hardware font that is closest in number to the font you requested. 
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You can retrieve the current value of the text font with the ASK TEXT 
FONT statement. In addition, you can optionally retrieve the current 
text precision value. The following statement retrieves the font number 
and the precision string in the variables font_number and what _precision 
respectively. 


Example 


DECLARE LONG which_font, & 
STRING what_precision 
ASK TEXT FONT which_font, what_precision 


4.2 Setting the Character Height 


The SET TEXT HEIGHT statement lets you set the height with which 
characters of text are drawn. The measurement for text height reflects 
the height of the uppercase letters compared to the height of the default 
drawing board: the height of the default drawing board is 1 unit, and th: 
default height of uppercase characters is 0.035 on the same scale. When 
you change the height of the text characters, any subsequent GRAPH 
TEXT statement writes the text in the new height. Lowercase characters 
are drawn in proportion to the height of the uppercase characters ac- 
cording to the specifications in the font design. The following statement 
increases the height of the characters to a height of 0.05. 


SET TEXT HEIGHT 0.05 


The accuracy of the height in the display is affected by the precision usec 
in a previous SET TEXT FONT statement. To achieve the exact height yo 
specify, text should be drawn with software fonts with STROKE precisior 
Hardware fonts with CHARACTER and STRING precision both map the 
height you request to the closest character size your device supports. 


The ASK TEXT HEIGHT statement retrieves the current value for the tex 
height and stores the value in a real variable you supply. This value can 
be used to reset the height of characters at another point in your progran 


ASK TEXT HEIGHT height_var 


The following example illustrates the use of the SET TEXT HEIGHT and 
ASK TEXT HEIGHT statements. 
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Example 


DECLARE SINGLE old_height 

ASK TEXT HEIGHT old_height 

SET TEXT FONT -3, "STROKE" 

SET TEXT HEIGHT 0.08 

GRAPH TEXT AT 0.05,0.7 : "This is height 0.08" 


SET TEXT HEIGHT old_height 
GRAPH TEXT AT 0.05,0.5 : "This is back to the last setting" 


Output 


eee 


This is height 0.08 


- 


This [9 hack to the last setting 


a 


When you change the window height with the SET WINDOW statement, 


you may also have to change the text height. For more information about 
changing the window height, see Chapter 5. 
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4.3 Setting the Character Height-to-Width Ratio 


Each font has a specified width for each character directly related to 

the height. Therefore, when you change the height of a character, you 
automatically change the width proportionately. You can alter the normal 
proportions of each character with the SET TEXT EXPAND statement. Thi 
initial value of the text width is 1.0, which displays characters with the 
height-to-width ratio specified in the font design. The following example 
demonstrates the use of the SET TEXT EXPAND statement by drawing the 
uppercase R and changing the height-to-width ratio. The ratio you supply 
must be greater than zero. 


Example 


DECLARE STRING CONSTANT text_string = "RRR" 
t+ 

{Set height but display normal proportions 
t- 

SET TEXT FONT -3 , "STROKE" 

SET TEXT HEIGHT 0.05 

GRAPH TEXT AT 0,0.8: text_string 

I+ 

!Change the height-to-width value 

t- 

SET TEXT EXPAND 3 

GRAPH TEXT AT 0,0.6 : text_string 

'+ 

Alter the height-to-width ratio, same height 
! 


SET TEXT EXPAND 6 


GRAPH TEXT AT 0,0.4 : text_string 
END 
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Output 


RRR 
rR rRFR 


= R= FR 


a eee eee 


Z2K-4913-86 


The ASK TEXT EXPAND statement lets you retrieve the current height- 
to-width ratio. You can use this value to reset the ratio later in your 


program. 


Example 


DECLARE SINGLE how_wide 
ASK TEXT EXPAND how _wide 


SET TEXT EXPAND 2.0 


SET TEXT EXPAND how_wide 


4 Setting the Spacing Between Characters 


Just as each font has a specified height-to-width ratio, each font has a 
specified amount of space between adjacent characters. The default space 
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value between characters is zero and is set by the font design. You can 
change this value with the SET TEXT SPACE statement. Characters are 
drawn further apart when you supply this statement with a positive valu 
If you supply a negative value, the characters are drawn closer together. 
The following example illustrates the effect of the SET TEXT SPACE 
statement. 


Example 


SET TEXT FONT -8 , "STROKE" 
SET TEXT HEIGHT 0.04 


SET TEXT SPACE -0.2 
GRAPH TEXT AT 0.1,0.8 : "These characters are tight" 


SET TEXT SPACE 0 
GRAPH TEXT AT 0.1,0.6 : "This spacing is specified by the font" 


SET TEXT SPACE 0.2 
GRAPH TEXT AT 0.1,0.4 : "These characters are spaced out" 


Output 


a: 


Theecharuteascretight 
This spacing ts specified by the font 


These charactare are spaced out 


ee ee eee 


2K-4911-86 


You can retrieve the current value for the spacing between characters wii 
the ASK TEXT SPACE statement, which assigns the value to the numeri: 
variable you supply. 


ASK TEXT SPACE spaced_out 
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.5 Setting the Text Angle 


Text is normally drawn with a horizontal orientation; that is, the first 
character is placed on the left and subsequent characters are drawn to 
the right along a horizontal base. This is the default angle value of zero. 
Like other text attributes, the text angle can be changed. To do this, you 
supply the SET TEXT ANGLE statement with a numerical value for the 
text angle. The value can be in either radians or degrees, according to 
the option you select with the OPTION statement. A nonzero text angle 
value causes text to be rotated from the normal orientation by the number 
of degrees or radians specified. Text rotation is in a counterclockwise 
direction; angles that are integer multiples of 180° display strings of 
characters horizontally and angles that are integer multiples of 90° display 
text vertically. Negative values cause the text to be rotated in a clockwise 
direction. 


The following example illustrates the effect of the SET TEXT ANGLE 
statement: 


Example 


1+ 

'Set angle option to degrees 

!- 

OPTION ANGLE = DEGREES 

SET TEXT HEIGHT 0.05 

SET TEXT FONT -16, "STROKE" 

SET TEXT ANGLE 90 

GRAPH TEXT AT 0.5,0.5 : "90 degrees" 
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SET TEXT ANGLE 180 

GRAPH TEXT AT 0.45,0.5 : "180 degrees" 
SET TEXT ANGLE 270 

GRAPH TEXT AT 0.5,0.45 : "270 degrees" 
'+ 

'Reset to the default angle 

!- 

SET TEXT ANGLE 0 

GRAPH TEXT AT 0.55,0.5 : "0 degrees" 
END 


Output 


90 deyrees 


s92.69P 0a! 0 degrees 


saashap O22 


ee eee eee eee ea 


ZK-4914-86 


The corresponding ASK TEXT ANGLE statement assigns the current value 
of the text angle to a numeric variable you supply, for example: 


OPTION ANGLE = DEGREES 
DECLARE SINGLE turn 
ASK TEXT ANGLE turn 
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6 Setting the Text Path 


The normal text path places each character to the right of the previous 
character. The text in this manual is printed with a normal, or RIGHT, 
text path. Changing the text path is useful for labeling the axes in graphs. 
You can change the text path of the individual characters with the SET 
TEXT PATH statement. You supply a string expression for the path. You 
can enter the string in upper- or lowercase characters. Valid values for the 
string expression are 


e RIGHT (the default) 


e LEFT 
e UP 
e DOWN 


Characters are placed according to the value specified in the SET TEXT 
PATH statement as well as the current value of the text angle. The 
following example illustrates the four possible text paths using the default 
text angle: 


Example 


OPTION ANGLE = DEGREES 

SET TEXT FONT -11 , "STROKE" 
SET TEXT HEIGHT 0.05 

1+ 

!Change the text path 

{- 

SET TEXT PATH "Up" 

GRAPH TEXT AT 0.4,0.7 : "Up" 


SET TEXT PATH "Left" 
GRAPH TEXT AT 0.4,0.5 : "Left" 
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SET TEXT PATH "Down" 
GRAPH TEXT AT 0.4,0.3 : "Down" 
t+ 


{Reset path to default 

'- 

SET TEXT PATH "Right" 

GRAPH TEXT AT 0.1,0.1 : "Right" 
END 


Output 


Right x 


2K 4912.86 


You can retrieve the current value of the text path with the correspondin; 
ASK TEXT PATH statement. You supply this statement with a string 
variable for the path. 


DECLARE STRING which_way 
ASK TEXT PATH which_way 
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7 Setting the Text Justification 


Text on a printed page is usually justified flush against the left margin, 
and is often justified on the right margin also. The text in this manual 
is justified only on the left margin. In VAX BASIC, you can justify text 
strings in a variety of ways. 


The normal alignment of text strings varies with the direction of the text 
path, as shown in Table 4-1. For example, each of the words in this 
sentence follows a RIGHT text path with the horizontal justification at the 
left of each word and the left of each page. The vertical justification is at 
the base of each word. 


Execution of a SET TEXT JUSTIFY statement allows you to alter the 
normal alignment of the text relative to the starting point you specify. 
This statement requires two arguments: string expressions for both the 
horizontal and vertical components of justification. The valid values for 
these string expressions are listed in Table 4-2. The values of NORMAL 
refer to the normal alignment as specified in Table 4-1. Following is an 
example of a SET TEXT JUSTIFY statement: 


SET TEXT JUSTIFY "Left" , "Base" 


Table 4-1: Normal Text Alignment 


Normal Horizontal Normal Vertical 
Text Path Alignment Alignment 
RIGHT LEFT BASE 
LEFT RIGHT BASE 
UP CENTER BASE 
DOWN CENTER TOP 


The text starting point refers to the x- and y-coordinates you supply with 
the GRAPH TEXT statement. For instance, in the following statement, the 
text starting point is 0.2,0.5. 


GRAPH TEXT AT 0.2,0.5 :"Sample text" 
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Table 4-2: Text Justification Values 


Component 


Horizontal 


Vertical 


Values 
NORMAL 
LEFT 


CENTER 


RIGHT 


NORMAL 


TOP 


CAP 


HALF 


BASE 


BOTTOM 


. Explanation 


Varies with the text path 


Leftmost character placed at the text startin 
point 

Center of the text string placed at the text 
starting point 


Text string placed so that the rightmost 
character in the text string ends at the text 
starting point 


Varies with the text path 


Top of the text string aligned with the text 
starting position 


Capline of the text string (highest point of 
the uppercase letters) aligned with the text 
starting position 


Starting point placed beginning an imaginar 
horizontal line through the middle of the te: 
string 

Baseline of the text string aligned with the 
starting point 


Bottom of the text string (lowest point of 
letters such as p and q) aligned with the 
starting position 


The following example illustrates many of the ways you can justify 

text. For purposes of illustration, the starting point for each text string 

is emphasized with a line beginning at the same point as the text string 
starting point. The example uses the default text angle of 0°. The first 
argument represents the value of the horizontal component of justificatior 
and the second argument represents the vertical component. Note that th 
values for NORMAL are dependent on the current text path, which in thi 
case is the default, RIGHT. 
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Example 


SET TEXT HEIGHT 0.04 
SET TEXT FONT -3 , "STROKE" 
SET LINE COLOR 2 


SET TEXT JUSTIFY "NORMAL", "NORMAL" 
GRAPH TEXT AT 0.4,0.95 : "Normal/normal" 
GRAPH LINES 0.4,0.95; 0.6,0.95 


SET TEXT JUSTIFY "NORMAL", “TOP” 
GRAPH TEXT AT 0.4,0.85 : "Normal/top" 
GRAPH LINES 0.4,0.85; 0.6,0.85 


SET TEXT JUSTIFY "NORMAL" , "CAP" 
GRAPH TEXT AT 0.4,0.75 : “Normal/cap" 
GRAPH LINES 0.4,0.75; 0.6,0.75 


SET TEXT JUSTIFY "NORMAL" , "HALF" 
GRAPH TEXT AT 0.4,0.65 : "Normal/half" 
GRAPH LINES 0.4,0.65; 0.6,0.65 


SET TEXT JUSTIFY "NORMAL" , “BASE* 
GRAPH TEXT AT 0.4,0.55 : "Normal/base" 
GRAPH LINES 0.4,0.55; 0.6,0.55 


SET TEXT JUSTIFY "NORMAL" , "BOTTOM" 
GRAPH TEXT AT 0.4,0.45 : "Normal/bottom" 
GRAPH LINES 0.4,0.45; 0.6,0.45 


SET TEXT JUSTIFY "LEFT" , "NORMAL" 
GRAPH TEXT AT 0.4,0.35 : "Left/normal" 
GRAPH LINES 0.4,0.35; 0.6,0.35 


SET TEXT JUSTIFY "CENTER", "NORMAL" 
GRAPH TEXT AT 0.4,0.25 : “Center/normal" 
GRAPH LINES 0.4,0.25; 0.6,0.25 
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SET TEXT JUSTIFY "RIGHT", "NORMAL" 
GRAPH TEXT AT 0.4,0.15 : "Right/normal" 
GRAPH LINES 0.4,0.15; 0.6,0.15 

END 


Output 


hs \ 





eae 


The following example changes the justification, path, and height of the 
text to label a simple bar chart. The chart shows the reported number 
of cases of communicable diseases in children in a small community 
during one year. The example includes the data within the program. 
Alternatively, if data is stored in a file, the file can be opened and read in 
the usual manner from within the program. 


Example 


OPTION TYPE = EXPLICIT 
DECLARE SINGLE start_y 
DECLARE LONG loop 
RECORD medical_record 
STRING disease 
SINGLE patients 
END RECORD medical_record 
DECLARE medical_record statistics (4) 
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{+ 

'Get the data 

1- 

DATA “Mumps",0.07,"Measles",0.15, 
"Chicken Pox", 0.60,"Scarlet Fever" ,0.12, 
"Tuberculosis" ,0.02 

FOR loop = 0 TO 4 

READ statistics (loop) : :disease 
READ statistics (loop) : : patients 

NEXT loop 

+ 

!Draw the axes 

t. 

GRAPH LINES 0.01,1; 0.01,0.2; 1,0.2 

t+ 

{Choose a new font 

1- 

SET TEXT FONT -3 , "STROKE" 

SET TEXT HEIGHT 0.04 

SET TEXT EXPAND 1.75 

GRAPH TEXT AT 0.1,0.05: "Number of Cases" 

SET TEXT JUSTIFY "CENTER" , "TOP" 

SET TEXT EXPAND 1 


& 


GRAPH TEXT AT loop/i0,0.2 : "|" FOR loop = 1 TO 10 
GRAPH TEXT AT loop/100,0.15 : STR$(loop) FOR loop = 10 TO 90 STEP 10 


V+ 
‘Reset the text attributes to label bars 
{- 
SET TEXT PATH "RIGHT" 
SET TEXT JUSTIFY "LEFT", "HALF" 
t+ 
!Plot the data 
f- 
SET AREA STYLE "HATCH" 
FOR loop = 0 TO 4 
start_y = 0.2 + (loop * 0.15) 
SET AREA STYLE INDEX INTEGER(start_y * 14) 
GRAPH AREA 0.01,start_y; 


statistics(loop) ::patients,start_y; 
statistics (loop): :patients,(start_y + 0.1); 


0.01, (start_y + 0.1) 
1+ 
!Label the bars 
{- 


& & & 


GRAPH TEXT AT statistics(loop)::patients,(start_y + 0.05) & 


: statistics (loop) : :disease 
NEXT loop 
END 
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You can retrieve the values of both the horizontal and vertical justificatior 
components by supplying string variables with the ASK TEXT JUSTIFY 
statement. 


ASK TEXT JUSTIFY which_horiz , which_vert 


4.8 Asking About Text Dimensions 


You can think of any graphics text string as being surrounded by an 
imaginary box. Many characters extend beyond the box in one or more 
directions, while other characters are defined within the perimeter of the 
box. As you alter the height, width, and angle of characters, you also 
alter the dimensions and positioning of the text box. Although you know 
the starting position of the text string, it is often difficult to predict where 
the text string will end. If you know where the text string ends, you 
know where to start a subsequent text string (for instance, if you want to 
concatenate strings). 


You can retrieve the dimensions of this text box for any text string with 
the ASK TEXT EXTENT statement. You supply the statement with the 
text string and the starting point, as well as two arrays to retrieve the 
coordinates of the corner points of the box. 
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If you want to attach an additional text string, you need to know the 
coordinates of the nearest point where subsequent text can be added. The 
coordinates for this concatenation point can be retrieved with the ASK 
TEXT POINT statement. The following example illustrates both the ASK 
TEXT EXTENT and the ASK TEXT POINT statements: 


Example 


OPTION TYPE = EXPLICIT 

DECLARE SINGLE concat_x, concat_y 

DECLARE STRING CONSTANT text_string = & 
"How much space does this text fill?" 

DIM SINGLE x_coords(3), y_coords(3) 


SET TEXT FONT -3 , "STROKE" 
SET TEXT HEIGHT 0.04 


ASK TEXT EXTENT , text_string & 
AT 0.0,0.6 & 
: x_coords, y_coords 

ASK TEXT POINT , text_string & 
AT 0.0,0.6 & 


: concat_x, concat_y 
' 
Display the text 
- 
GRAPH TEXT AT 0.0,0.6 : text_string 
! 
Use the text box coords to draw the text box 
'by graphing a hollow area 
!- 
SET AREA STYLE "Hollow" 
MAT GRAPH AREA x_coords , y_coords 
! 
iUse the concatenation point to add on a string 
t- 
GRAPH TEXT AT concat_x, concat_y : "VAX BASIC knows!" 
END 
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For another example using the ASK TEXT POINT statement, see the SET 
TEXT COLOR statement in Chapter 9. 


4.9 Summary 


This chapter has explained how to use the following statements: 


SET/ASK TEXT FONT 
SET/ASK TEXT HEIGHT 
SET/ASK TEXT ANGLE 
SET/ASK TEXT SPACE 
SET/ASK TEXT EXPAND 
SET/ASK TEXT PATH 
SET TEXT JUSTIFY 

ASK TEXT EXTENT 

ASK TEXT POINT 
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The examples so far in this manual have all placed graphics objects in the 
default drawing board, where 0,0 is a point in the bottom corner of the 
terminal screen. It is often desirable to change the scale and orientation of 
the coordinate plane. The following chapter shows you how to alter the 
drawing board to suit your own needs. 
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Chapter 5 
The Drawing Surface 


Using the default drawing board allows you to create simple graphics on 
your screen quickly and easily. At the same time, using the default limits 
flexibility in programming techniques and the format of screen displays. 
This chapter shows you how to define and extend the default drawing 
board to suit your own application and describes how to: 


e Change the window setting 
e Define transformations 
e Clip images 


1 Setting the World Window 


Whether you have plotted points on paper with a grid or plotted points 
in your mind’s eye, so far you have expressed the position of these points 
within the boundaries of the default drawing board. The default drawing 
board is also known as the world window. The coordinates that you use to 
define the points in the world window are known as world coordinates.’ 


The boundaries of the default world window are 0,1,0,1 for the left, right, 
bottom, and top edges respectively. The world coordinates of the points 
you have plotted have been contained within these same limits; that is, 
the x- and y-coordinates of points in the default world window have 
values ranging from 0 through 1. It is not always convenient or suitable 
to restrict the coordinates of points to values from 0 through 1, nor is it 
necessary. You can change the boundaries of the world window and the 
range of world coordinate values of points that can be displayed on your 
screen. 


1 Another common term for world coordinates is problem coordinates. 
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You can set the boundaries of the world window to your own preferenct 
For example, window boundaries of -20,20,-20,20 allow you to plot poir 
with negative as well as positive coordinates and accommodate 0,0 as th 
center point. Boundaries need not be symmetrical; you can define the 
x-axis as being, for example, 0 to 50, with a y-axis of 40 to 240. 


The boundaries you set merely reflect a scale. Whatever boundaries you 
select, VAX BASIC still displays graphics images on the same area on yo 
screen, unless you make further changes as described in later sections of 
this chapter. 


To set new boundaries for your world window, use the SET WINDOW 
statement. The following example sets the world window boundaries to 
be 0,100,0,100. The program displays a hexagon; the coordinates of the 
points of the hexagon can now range from 0 to 100 because of the new 
window boundaries. 


Example 


DECLARE LONG loop, SINGLE x, y 
t+ 
!Set the world window 
1- 
SET WINDOW 0,100,0,100 
!+ 
'Express coordinates in range of O to 100 
!- 
DATA 70,50,60,30,40,30,30,50,40,70,60,70,70,50 
1+ 
!Draw hexagon 
- 
SET LINE SIZE 5 
FOR loop = 0 TO 6 
READ x,y 
PLOT LINES x, y; 
NEXT loop 
END 
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In Chapter 2, an adjustment was made to the formula that produces 

the coordinate points for the sine curve. The adjustment was necessary 
because some values fall outside the default world window boundaries. 
When world window boundaries are set to accommodate negative values, 
this adjustment is no longer necessary. The following example sets the 
world window boundaries to 0,2*PI,-1,1. These boundaries accommodate 
the coordinate values of all points on the sine curve. This example also 
draws the axes. 
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Example 


OPTION TYPE = EXPLICIT 
DECLARE SINGLE loop_index, x, y 
t+ 
!Set the window boundaries 
t- 
SET WINDOW 0, 2*PI, -1, 1 
t+ 
!Draw in the axes 
!- 
PLOT LINES 0,0; 2*PI,0 ‘horizontal axis 
PLOT LINES 0,-1; 0,1 !vertical axis 
'+ 
!Plot the coordinates of points on sine curve 
f- 
SET LINE SIZE 3 
SET LINE COLOR 2 
FOR loop_index = 0 TO 2*PI STEP 0.1 
PLOT LINES loop_index, SIN(loop_index) ; 
NEXT loop_index 
PLOT LINES (2*PI + 0.1), SIN(2*PI + 0.1) 
END 


Output 
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When you set the window, you may also need to change the height of th 
text. The default text height is 0.035 world coordinate units. After you 
set new boundaries with the SET WINDOW statement, the proportion 
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of the text height in relation to the height of the world window changes. 
To maintain a text height that is equivalent to the default height, use the 
following formula: 


new_text height = max_height — min_height * 0.035 


Example 


SET WINDOW 0,10,500,800 
new_text_height = (800 - 500) * 0.035 
SET TEXT HEIGHT new_text_height 


Notice the values passed to the SET TEXT HEIGHT statement in the 
following example. The world window height is set from 0 to 2000; 
therefore, the default text height of 0.035 is no longer appropriate. The 
example alters the text height to a height suitable for the display. 


When you plot values on a graph, you can use the axes as measures of the 
values you are working with. You can set the world window to directly 
correspond to the values you are plotting. The following example sets 
the world window boundaries to correspond to the years 1979 through 
1986, and to the wheat yield in millions of bushels. The graph shows 
only the years under study. The axes are drawn well within the window 
boundaries to leave room for explanatory text on the axes. 


Example 


OPTION TYPE = EXPLICIT 

DECLARE LONG year 

DIM LONG bushels(1980 TO 1985) 

I+ 

!Set window boundaries to suit data 

t- 

SET WINDOW 1979,1986,0,2000 

'+ 

‘Initialize array with bushels per year data 


bushels(1980) = 1300 
bushels(1981) = 1400 
bushels(1982) = 1700 
bushels(1983) = 1000 
bushels(1984) = 1200 
bushels(1985) = 1600 
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I+ 

!Draw the axes 

'- 

GRAPH LINES 1980,2000; 1980,100; 1986,100 

+ 

!Plot the coordinates for bushels of wheat 

'- 

PLOT LINES : year,bushels(year); FOR year = 1980 TO 1985 
t+ 

!Set text font & height for headers 

t. 

SET TEXT FONT -1, "CHAR" 

SET TEXT HEIGHT 60 

GRAPH TEXT AT 1981,1900 : "WHEAT HARVEST" 

I+ 

!'Graph text for vertical axis 

f- 

SET TEXT PATH "DOWN" 

GRAPH TEXT AT 1979.5,1950 : "Millions of Bushels" 
'+ 

!Graph text for horizontal axis 

1- 

SET TEXT PATH "RIGHT" 

SET TEXT JUSTIFY "LEFT" , "TOP" 

GRAPH TEXT AT (year + 0.25),120 : "|" FOR year = 1980 TO 1985 
'+ 

!'Place markers on axis for years 

f- 

SET TEXT FONT -1, "STROKE" 

SET TEXT JUSTIFY "CENTER" , "NORMAL" 

GRAPH TEXT AT (year + 0.25),5 : NUM$(year) FOR year = 1980 TO 1985 
END 
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A complementary ASK WINDOW statement allows you to retrieve the 
values of the world window boundaries. For example, the following 
statement returns the implied boundary values in the variables left_1, 
right_1, bottom, and top. These values can be used to reset the world 
window at a later point in a program, or to calculate a suitable text height. 


Example 


DECLARE SINGLE left_i, right_1, bottom, top 


ASK WINDOW left_1,right_1, bottom, top 


I+ 


!Set text height to 1/10th of current window height 
1- 


SET TEXT HEIGHT ((top - bottom) /10) 


Both the SET WINDOW and ASK WINDOW statements accept an optional 


parameter for the transformation number. Transformations are explained 
in the following section. 
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5.2 Defining a Transformation 


So far, the images you have plotted on your drawing surface seem to be 
mapped directly onto the default drawing board on your screen. Howeve 
your screen can be any supported graphics device. Considerable work is 
done “behind the scenes” to make the image you plot portable to any 
graphics output device. In fact, the image you define in the world windo 
must go through a transformation to be displayed as output on any one o 
the devices supported by VAX GKS. 


A transformation is the procedure VAX BASIC performs on an image 
defined in a window so that the image can be displayed on one of the 
supported devices. Figure 5-1 illustrates the concept of this internal 
processing by showing how one image defined in world coordinates is 
displayed on different output devices. 
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igure 5-1: Transformations Let You Display Images on 
Many Supported Devices 
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The transformation occurs in an abstract square coordinate plane known 
as the Normalized Device Coordinate (NDC) space. VAX BASIC maps 

the image you define onto NDC space; this is known as a normalization 
transformation. The image is then mapped to the output device; this 

is known as the device transformation. You can alter the internal pro- 
cessing of images to define your own transformations and thereby gain 
increased flexibility in your graphics displays. This chapter describes only 
normalization transformations; device transformations are explained in 
Chapter 8. 


NDC space has boundaries that are always 0,1,0,1 for the left, right, 
bottom, and top boundaries respectively. You can select portions of NDC 
space in which to position your image, you can position several images 
onto NDC space, and you can select which portion of NDC space to map 


The Drawing Surface 5-9 
# 


Figure 5-2: 
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to your screen. Figure 5-2 illustrates how NDC space can be used to 
build up a screen display. Separate images can be defined in windows 
with different boundaries, projected onto different portions of NDC space 
and displayed as one composite image on the screen. This figure also 
illustrates the progression of any images from your drawing surface to 
NDC space, and from NDC space to your screen. 


Creating a Composite Image 


NDC Space 
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A transformation is defined using windows and viewports. A window is 
where an image is defined. A viewport is where an image is displayed or 
projected. The image defined in a window is projected onto a viewport. 
The progression of a transformation can be seen as a two-part process: 


1. An image is defined in the world window. 


2. The image in the world window is projected onto the world viewport 
in NDC space. 


When you change the world window or world viewport defaults, 
you are defining a new transformation. This process is illustrated in 
Figures 5-3, 5-4, and 5-5. 
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‘igure 5-3: The Transformation of an Image Through NDC Space 
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You alter the boundaries of the world window with the SET WINDOW 
statement, as shown in Section 5.1. The default world window bound- 
aries are 0,1,0,1. Figure 5-4 illustrates a world window of 0,100,0,100; 
coordinate values of points in this window can range from 0 through 100. 
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Figure 5-4: Defining an Image in a World Window 
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The image defined in the world window or drawing surface is projected 
onto the world viewport in NDC space, as shown in the following section 


5.3 Setting the World Viewport 


Each of the examples in Section 5.1 changes the boundaries for the world 
window without making any further changes. The images are still mappec 
to the default viewport on NDC space. You can select portions of NDC 
space and create more than one world viewport. 


Using the wheat yield example, you can place the same graph in the lowe: 
left corner of NDC space, rather than placing it in all of NDC space. The 
default world viewport is all of NDC space, with boundaries of 0,1,0,1. 
The SET VIEWPORT statement allows you to set new boundaries for 

the world viewport. You can use either all of NDC space or a portion 

of it: you cannot use boundary values beyond the range of 0 through 1. 
Figure 5-5 illustrates a world viewport of 0,0.5,0,0.5. 
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Figure 5-5: Projecting an Image onto a World Viewport 
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The following statement limits the world viewport to the lower left corner 
of NDC space. If no other changes are made, the addition of this one 
statement prior to any graphics output statements in the program causes 
the line chart to be displayed in the lower left corner of the display area. 
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Example 


SET VIEWPORT 0,0.7,0,0.7 
t+ 


{Continue with output of wheat yield data 
f- 


Output 
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Notice that a square diagram has been transformed to a square portion 
of NDC space. When the window and viewport shapes do not match, 
the proportions are distorted. The ratio of one scale to another is known 
as the aspect ratio. When the aspect ratio is not 1:1, distortion will be 
apparent to some degree. 


The following display demonstrates the scaling problems that can occur. 
In this case a square world window is transformed to a rectangular world 
viewport. The mismatch of shapes results in a distortion of the scales. 
The aspect ratio is discussed further in Chapter 8 in relation to device 
transformations. 
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Example 


I+ 

!Change the viewport for the default transformation 
t- 

SET VIEWPORT 0,0.5,0,1 

'+ 

!Continue with wheat/year data as before 

{- 


Output 
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You can retrieve the boundaries of the current viewport with the ASK 
VIEWPORT statement. For example: 


ASK VIEWPORT left_1,right_1,bottom,top 
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5.4 Multiple Transformations 


Several images can each be placed in different sections of NDC space, 
and then all of NDC space displayed on the screen. Each image that 
requires a different window or viewport requires a transformation; this 
opens up the potential for confusion between one transformation and 
another. To keep track of the window and viewport you select for a 
particular display, you can identify each transformation with a number. 
The transformation number must be an integer from 1 to 255. Once a 
particular transformation has been defined, you can refer to it again by the 
same number. 


Transformations can be optionally specified in the SET WINDOW and SET 
VIEWPORT statements explained earlier. The default transformation is 1. 
At the start of program execution, transformation 1 consists of a window 
and viewport with boundaries of 0,1,0,1. You can redefine transformation 
1 to your choice of window and viewport boundaries. 


If you do not specify a transformation number, VAX BASIC uses the 
default transformation of 1. A statement such as the following sets up 
the new window boundaries for transformation 1, because no other 
transformation is specified. 


SET WINDOW 0,100,0,100 


In the examples so far in this chapter, only one transformation has been 
defined within a program. When several transformations are defined 

in a program, you should specify the transformation number in SET 
VIEWPORT and SET WINDOW statements. 


SET VIEWPORT , TRAN 2 : 0.5,1,0.5,1 


Only one transformation is current for displaying points at a given time 
during execution. You can specify which transformation is the current one. 
Otherwise, the last transformation you set in your program remains the 
current transformation. The current transformation is explicitly established 
with a SET TRANSFORMATION statement, for example: 


SET TRANSFORMATION 2 


You can implicitly establish the current transformation with a SET 
WINDOW or SET VIEWPORT statement. For instance, the following 
statement implicitly sets the current transformation to 7. The window 
boundaries for any other transformations you may have defined remain 
intact and unaffected by this SET VIEWPORT statement. 
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SET VIEWPORT, TRAN 7 : 0,0.5,0,0.5 


Subsequent graphics output statements use transformation 7 until VAX 
BASIC executes another SET TRANSFORMATION, SET WINDOW, or 
SET VIEWPORT statement. The ASK TRANSFORMATION statement 
allows you to retrieve the number for the transformation that is current, 
for example: 


DECLARE LONG current 
ASK TRANSFORMATION current 


In the following example, transformation 1 is redefined and an additional 
transformation, 2, is defined. A SET TRANSFORMATION statement sets 
the current transformation to 1 for subsequent graphics output. 


Example 


!Tran 1 becomes the current transformation 
SET WINDOW , TRAN 1 : 50,100,0,250 


!Tran 2 now becomes the current transformation 
SET WINDOW , TRAN 2 : -5,5,-5,5 


!Tran 1 now becomes the current transformation 
SET TRANSFORMATION 1 
GRAPH AREA : 50,0; 50,250; 100,250; 100,0 


The following example displays the image of a swan using the transforma- 
tion identified as 1. Notice that the transformation number is also referred 
to in the SET WINDOW and SET VIEWPORT statements. In this example, 
only one transformation is defined. The data provided in this picture is 
used in examples in later chapters of this manual. The image of the swan 
is transformed to the top right corner of NDC space. 


Example 


PROGRAM Draw_swan 
EXTERNAL PICTURE swan 
SET WINDOW , TRAN 1 : 0,100,0,100 
SET VIEWPORT , TRAN i : 0.5,1 
DRAW swan 

END PROGRAM 
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PICTURE swan 
OPTION TYPE = EXPLICIT 
DECLARE LONG counter 
DIM SINGLE x_array(98) ,y_array (98), 
mark_x(3) ,mark_y(3), 
eye_x(2) ,eye_y(2), 
wing_area_x(28) ,wing_area_y (28) 
Outline_data: 
DATA 82,80.5,80,80.5,75,81,72,81.5,70,83.5,68,84,65,84.5, 
63 ,83,61,82,60.5,80,60.55,78,62.5,75,64,70,66.5,67,70,62.5, 
72 ,60,75,57,78,54,80,50,82.5,46,84, 40, 86.5,30,87,24.5,87,20, 
86,17.5,83.5,13.5,82,12,80,11.5,77,10, 70,9,65,9,60,9.2,53,10, 
50,10.5,40,12,35,14,30,18,27,20,20,27.5,14,36,12,40,8.5,50,8, 
§9,10,52.5,14,48,20,45,17,50,16.75,57, 20,60,18,61.5,20,67,27, 
75 ,27.5,72,37,85,36,80,34,75,32.25,70,32,65,32.25,60,32.35, 
58, 34,53,35,50,38,45,40,41,43.5,38,48,34,52,32.5,60,31,63,32, 
69.5,35.5,70.5,37,72,40,70.5,43,69.5,47,68.5,50,65.5,55,62.5, 
60 ,60,65,57.5,70,55,75,54,80,54.25,83,54,84.5,55,87,59,90,60, 
0,92,7 
2 5 


RP & & 


Re & Re ke kp kp kp RP kp KP & 


91 ,63,92.25 ,66.5,93,68,92.75,70,92,71.5,91,73,89.5,74,87,75.5, 
85,78,84,80,82,82,82,80,80.5,82,80. 


Wing_area_data: 
DATA 32.35,58,34,53,35,50,38,45,40,41,43.5,38,48,34,52,32.5, 
60,31,63,32,69.5,35.5,70.5,37,32.35,68,30.05,50,28,42,27.5, 
44.5,28.5,30,30,24,31.5,20,35,14,40,12,45,13,50,14,63,15, 
58.5,17.5,61,19,64.5,22,69,30,70.5,37 


& & & 


Head_mark_data: 
DATA 73,87,70,86,73,85,73.15,86,67,89,69,88,70.5,90 


READ x_array(counter),y_array(counter) FOR counter = 0% TO 98% 

READ wing_area_x(counter) ,wing_area_y(counter) FOR counter = 0% TO 28% 
READ mark_x(counter) ,mark_y(counter) FOR counter = 0% TO 3% 

READ eye_x(counter), eye_y(counter) FOR counter = 0% TO 2% 


Display_the_swan: 

SET LINE COLOR 3% 

SET LINE STYLE 1 

MAT GRAPH LINES x_array,y_array 
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SET AREA STYLE "PATTERN" 
MAT GRAPH AREA wing. area_x,wing_area_y 
SET LINE COLOR ‘2% 
MAT GRAPH LINES eye_x,eye_y 
MAT GRAPH AREA mark_x,mark_y 
END PICTURE 


Output 
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You can also specify a transformation in the ASK WINDOW and ASK 
VIEWPORT statements, for instance: 


ASK WINDOW , TRAN 4 : left_i,right_1, bottom, top 


Use of these statements is further illustrated in the following example, 
which transforms one face onto fourteen different portions of NDC space. 
Adding some text makes a total of fifteen transformations. Without 
changing the current transformations, all of the faces would have been 
placed directly over the first in the top left section of NDC space. This 
example uses a simple picture called face. Notice that the transformations 
are defined before each picture invocation. Chapter 6 provides details 
governing the use of pictures. 
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Example 


PROGRAM draw_crowd 

EXTERNAL PICTURE face 

i+ 

{Select the default world window for all transformations 
t- 

SET WINDOW , TRAN loop : 0,1,0,1 FOR loop = i TO 15 
t+ 


!Set up fourteen different world viewports in NDC space 
{- 


SET VIEWPORT , TRAN 1: 0O, 0.2, 0.8, 1 
SET VIEWPORT , TRAN 2: 0.2, 0.4, 0.8, 1 
SET VIEWPORT , TRAN 3 : 0.4, 0.6, 0.8, 1 
SET VIEWPORT , TRAN 4: 0.6, 0.8, 0.8, 1 
SET VIEWPORT , TRAN 5 : 0.8, 1, 0.8, 1 
SET VIEWPORT , TRAN 6 : 0.1, 0.3, 0.6, 0.8 
SET VIEWPORT , TRAN 7: 0.3, 0.5, 0.6, 0.8 
SET VIEWPORT , TRAN 8: 0.5, 0.7, 0.6, 0.8 
SET VIEWPORT , TRAN 9 : 0.7, 0.9, 0.6, 0.8 
SET VIEWPORT , TRAN 10 : 0, 0.2, 0.4, 0.6 
SET VIEWPORT , TRAN 11 : 0.2, 0.4, 0.4, 0.6 
SET VIEWPORT , TRAN 12 : 0.4, 0.6, 0.4, 0.6 
SET VIEWPORT , TRAN 13 : 0.6, 0.8, 0.4, 0.6 
SET VIEWPORT , TRAN 14: 0.8, 1, 0.4, 0.6 


t+ 
'Set up the world viewport for the 
t- 
SET VIEWPORT , TRAN 15 : 0,1,0,1 
'+ 
!Draw a face in each world viewport 
t- 
FOR tran_id = 1 TO 14 
SET TRANSFORMATION tran_id 
DRAW face 
NEXT tran_id 


A 


Write_the_text: 

SET TRANSFORMATION 15 

SET TEXT HEIGHT 0.08 

GRAPH TEXT AT 0,0.2 : "Your BASIC Crowd" 
END PROGRAM 


5-20 The Drawing Surface 


PICTURE face 
1+ 
!'Set up one image of the face on the world window 
1- 
OPTION TYPE = EXPLICIT 
DECLARE SINGLE turn,increment, 
head_x(40) ,head_y(40), 
nouth_x(6) ,mouth_y(6), 
LONG loop, counter, 
tran_id 
DECLARE SINGLE CONSTANT radius = 0.5 
DECLARE LONG CONSTANT npoints = 40 


S&eee 


Head: 
increment = 2 * PI/npoints 
turn = 0 


FOR loop = 0 TO npoints -1 
head_x(loop) = COS(turn) * radius + 0.5 
head_y(loop) = SIN(turn) * radius + 0.5 
turn = turn + increment 


NEXT loop 
head_x(40) = head_x(0) 
head_y(40) = head_y(0) 
Mouth: 
DATA 0.25,0.45,0.34,0.36,0.4,0.325,0.5, & 


0.324,0.6,0.325,0.66,0.365,0.75,0.425 
READ mouth_x(loop) ,mouth_y(loop) FOR loop = 0% TO 6% 

Draw_face: 

MAT GRAPH LINES head_x,head_y 

MAT GRAPH LINES mouth_x,mouth_y 

!Eyes 

SET POINT STYLE 4 

GRAPH POINTS 0.35,0.65; 0.65,0.65 
END PICTURE 
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5.5 Clipping the Image 


The boundaries of the world window are also the limits of the world 
coordinates that are displayed on your screen. If you plot points beyond 
the limits of the world window you have defined, these points are also 
beyond the limits of the world viewport and are not displayed by default. 
This is known as clipping. Any points that are beyond the boundaries of 
the world window are clipped by default. VAX BASIC clips images at the 
boundaries of the world viewport. Clipping affects all graphics objects: 
lines, points, areas, and text. 


You can control the clipping feature with the SET CLIP statement. The 
SET CLIP statement accepts string expressions equivalent to “ON” or 
“OFF”. The default clipping status is ON. When you turn clipping off, 
VAX BASIC displays graphics objects that are beyond the boundaries of 
the world window but are still within the boundaries of NDC space.” 


2 The entire NDC space is also the default device window. When the device window is altered and clippin 
is turned off, objects that are beyond the boundaries of the world window but are within the boundarie 
of the device window are displayed. For more information about device transformations, see Chapter 8. 
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The following example defines a kite and string. Only the string is plotted 
within the world window; the points for the body of the kite are plotted 
in coordinates that are beyond the extent of the world window. With 
clipping on (the default), only the kite string is displayed. 


Example 


OPTION TYPE = EXPLICIT 
DECLARE LONG loop 
DIM SINGLE kite_x(19) ,kite_y(19) 
SET WINDOW , TRAN 1 : 0,50,0,50 
SET VIEWPORT , TRAN 1 : 0,0.5,0,0.5 
+ 
'Get the data for the kite 
!'Some points are beyond the world window 
!- 
DATA 80,90, 90,70, 50,50, 80,90, 
50,80, 90,70, 50,80, 50,50, 
50,50, 45,45, 45,40, 45,35, 
40,30, 34,28, 30,27, 25,20, 
32,20, 30,15, 10,20, 10,12 
READ kite_x(loop) ,kite_y(loop) FOR loop = 0% TO 19% 
I+ 
!'Draw the kite 
t- 
MAT GRAPH LINES kite_x, kite_y 
GRAPH POINTS 68,82; 77.5,79.5 


Se & & 
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Output 
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To display the whole kite, you must change the clipping status with the 
following statement: 


SET CLIP "OFF" 


Adding this statement to the previous example turns off the clipping and 
displays both the kite and the string: 
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Example 


OPTION TYPE = EXPLICIT 

DECLARE LONG loop 

DIM SINGLE kite_x(19) ,kite_y(19) 

SET WINDOW , TRAN 1 : 0,50,0,50 

SET VIEWPORT , TRAN 1 : 0,0.5,0,0.5 

DATA 80,90, 90,70, 50,50, 80,90, 
50,80, 90,70, 50,80, 50,50, 
50,50, 45,45, 45,40, 45,35, 
40,30, 34,28, 30,27, 25,20, 
32,20, 30,15, 10,20, 10,12 

READ kite_x(loop) ,kite_y(loop) FOR loop = 0% TO 19% 

I+ 

!Turn off clipping 

1- 

SET CLIP "OFF" 

'+ 

!Draw the kite 

ee 

MAT GRAPH LINES kite_x, kite_y 

GRAPH POINTS 68,82; 77.5,79.5 

END 


S&eee 


Output 
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In the following example, the world window is set to 50,100,50,100. 
However, the coordinates for the points of the swan range from 0 through 
100. All points that extend beyond the world window are cut off, or 
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clipped, in the first display because the clipping status is on by default. 
Clipping is turned off for the second screen; therefore, all of the swan is 
displayed. 


Example 
EXTERNAL PICTURE swan 


I+ 

!'Set up points for swan in world window 

!Coordinates in picture are spread from 0 through 100 
'Half of swan is out of the world window 

t- 

SET WINDOW , TRAN 1 : 50,100,50,100 

SET VIEWPORT , TRAN 1 : 0.5,1,0.5,1 

SET TEXT HEIGHT 2.5 


1+ 

!Leave default clipping 

!Display screen 1 

f- 

GRAPH TEXT AT 55,70 : "CLIPPING IS ON" 
DRAW swan 

SLEEP 5% 

CLEAR 


1+ 

!Turn off clipping 

1- 

SET CLIP "OFF" 

V+ 

!Display screen 2 

f- 

GRAPH TEXT AT 55,70 : "CLIPPING IS OFF" 
DRAW swan 

END 
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Output Screen 1: 
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Output Screen 2: 
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In the following example, two fuses are presented without the text labels 
when clipping is on for the first screen. For the second screen, the clippir 
is turned off; therefore, the labels are displayed. 


Example 


OPTION TYPE = EXPLICIT 

EXTERNAL PICTURE fuse_shell, good_fuse, bad_fuse 
SET WINDOW , TRAN 1 : 0,100,0,100 
SET VIEWPORT , TRAN 1 : 0,0.5,0,0.5 
SET TEXT COLOR 2 

SET TEXT HEIGHT 6 

+ 

!Draw good fuse 

!- 

GRAPH TEXT AT 30,110 : "GOOD FUSE" 
DRAW fuse_shell 

DRAW Good_fuse 

$+ 

!Draw bad fuse 

t- 

SET WINDOW , TRAN 2 : 0,100,0,100 
SET VIEWPORT , TRAN 2 : 0.5,1,0,0.5 
GRAPH TEXT AT 30,110 : "BAD FUSE" 
DRAW fuse_shell 

DRAW Bad_fuse 

SLEEP 5% 

CLEAR 

t+ 

!'Turn off clipping, re-draw with text labels 
t- 

SET CLIP "OFF" 

SET TRANSFORMATION 1 

GRAPH TEXT AT 30,110 : "GOOD FUSE" 
DRAW fuse_shell 

DRAW Good_fuse 

SET TRANSFORMATION 2 

GRAPH TEXT AT 30,110 : "BAD FUSE" 
DRAW fuse_shell 

DRAW Bad_fuse 

END 


5-28 The Drawing Surface 


PICTURE fuse_shell 
DECLARE LONG loop 


DIM SINGLE outer_x(8), outer_y(8), & 
inner_x(3), inner_y(3), & 
edge_x(3), edge_y(3) 

DATA 20,90,80,90,80,70,75,70, & 


75 ,60, 25 ,60,25,70,20,70,20,90 
READ outer_x(loop) ,outer_y(loop) FOR loop 
DATA 30,80,30,40,40, 40, 40,80 
READ inner_x(loop),inner_y(loop) FOR loop = 0% TO 3% 
DATA 70,80,70,40,60,40,60,80 
READ edge_x(loop) ,edge_y(loop) FOR loop = O% TO 3% 
SET LINE SIZE 1 
SET LINE COLOR 1 
MAT GRAPH LINES outer_x,outer_y 
MAT GRAPH LINES inner_x,inner_y 
MAT GRAPH LINES edge_x,edge_y 
GRAPH LINES 20,85; 80,85 
SET POINT STYLE 1 
SET POINT COLOR 2 
GRAPH POINTS 35,62.5;65,62.5 
END PICTURE 


0% TO 8% 


PICTURE Good_fuse 
DECLARE LONG loop 
DIM SINGLE fuse_x(10) , fuse_y(10) 
DATA 40,65,45,70,43,70,45,72,48,78,50,79,52, & 
78,55,72,57,70,55,70,60,65 
READ fuse_x(loop),fuse_y(loop) FOR loop = 0% TO 10% 
SET LINE SIZE 4 
SET LINE COLOR 2 
MAT GRAPH LINES fuse_x,fuse_y 
END PICTURE 
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PICTURE Bad_fuse 
DECLARE LONG loop 
DIM SINGLE left_x(2) ,left_y(2) ,right_x(2) ,right_y(2) 
DATA 40,65,57,70,45,70,55, 70,43, 70,60,65 
READ left_x(loop), left_y(loop), & 
right_x(loop), right_y(loop) FOR loop = 0% TO 2% 
SET LINE SIZE 4 
SET LINE COLOR 2 
MAT GRAPH LINES left_x,left_y 
MAT GRAPH LINES right_x,right_y 
END PICTURE 


Output Screen 1: 
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Output Screen 2: 
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A complementary ASK CLIP statement allows you to retrieve the clipping 
status in a string variable you supply. You can then reset the clipping 
status with this variable later in your program. 


ASK CLIP clip_stat 


mmary 


Creating a graphics image can involve each of the following steps: 


e Setting world window boundaries with the SET WINDOW statement 


¢ Setting world viewport boundaries with the SET VIEWPORT state- 
ment 


e Setting the current transformation explicitly with the SET 
TRANSFORMATION statement, or implicitly with the SET WINDOW or 
SET VIEWPORT statement 


¢ Clipping the graphics image at the world viewport boundaries with 
the SET CLIP statement 
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None of these steps is required. VAX BASIC includes convenient default: 
so that, if you choose to, you can safely ignore these options. However, 
setting the world window boundaries alone provides you with a significar 
increase in flexibility for minimum effort. Defining transformations allow 
you to create multiple images and complex screens. Another kind of 
transformation, known as a device transformation, is possible. Device 
transformations are described in Chapter 8. 


This chapter has introduced statements that can add a great deal of 
flexibility to your programs. Graphics subprograms (pictures) take full 
advantage of this additional flexibility. The next chapter shows you how 
to use pictures to create complex images. 
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Chapter 6 
Creating Complex Images 


When you invoke a graphics subprogram, or picture, you can easily 
perform various transformations and create complex images. This chapter 
explains how to define VAX BASIC graphics pictures of varying complexity 
and invoke them with a variety of transformations. 


.1 Pictures 


A graphics picture is the definition of an image in a block of code. The 
definition is delimited by the PICTURE and END PICTURE statements. 
The picture must have a valid VAX BASIC identifier and the name must 
not be the same as a SUB or FUNCTION subprogram, or a PROGRAM 
unit. 


PICTURE which_picture 


END PICTURE 

This block of code can be invoked in a fashion similar to a VAX BASIC 
SUB or FUNCTION subprogram, and follows the standard VAX/VMS 

calling procedures for passing parameters. Pictures should be declared 


with the EXTERNAL statement in the program unit that invokes the 
picture. You invoke a picture with the DRAW statement. 
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PROGRAM calling 
EXTERNAL PICTURE sample_name(SINGLE) 
DRAW sample_name(val_ue) 


END PROGRAM 
PICTURE sample_name(SINGLE val_ue) 


END PICTURE 


VAX BASIC provides the END PICTURE and EXIT PICTURE statements 
to terminate execution of a picture. Execution of a STOP statement withir 
a picture definition terminates execution of the entire program. 


6.1.1 Simple Pictures 


You set up the definition of a graphics image in world coordinates within 
the PICTURE and END PICTURE statements. As with other VAX BASIC 
subprograms, you can pass parameters to a picture. 


The following picture defines a rectangle in terms of the left, right, bottorr 
and top boundaries. These boundaries are used to specify the world 
coordinates of each corner of the rectangle. 


Example 
PICTURE box(SINGLE left_1,right_1, bottom, top) 
PLOT LINES : left_1,top; & 

right_1,top; & 
right_1,bottom; & 
left_1, bottom; & 
left_1,top 

END PICTURE 


To invoke this picture, use the DRAW statement at an appropriate point 
in your program. The DRAW statement passes parameters to the picture. 
Parameters passed from the DRAW statement to the picture must agree ir 
_number and data type with the parameters listed in the picture definition. 
The picture box requires values for the box boundaries in the order 
specified. The DRAW statements in the following example invoke the 
picture box to draw several rectangles on the display area. Note that no 
_parameter-passing mechanisms are required in the DRAW or PICTURE 
statements because pictures are VAX BASIC subprograms and use the 
default passing mechanisms. After compilation, the main program and 
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any separately compiled programs should be linked together before 
execution. 


PROGRAM draw_boxes 
EXTERNAL PICTURE box(SINGLE ,SINGLE ,SINGLE, SINGLE) 
SET WINDOW 0,100,0,100 


DRAW box(0,30,60,90) 

DRAW box(70,85,20,80) 

DRAW box(25,50,15,40) 

DRAW box(40,60,30,40) 

DRAW box(25,95 , 25,75) 
END PROGRAM 


Output 


—— iC 


a 
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The following picture is an example that defines the image of an ellipse. 
The ellipse requires values for the height and width to be passed with 
the DRAW statement. This picture is based on the general formula of an 
ellipse centered at the point 0,0: 
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The variable a is one half of the major axis dimension of the ellipse, and 
b is one half of the minor axis dimension. This formula yields an ellipse 
whose major axis is on the y axis; later in the program a becomes Half_ 
height, and b becomes Half_width. Solving this equation for y yields the 
alternate form: 


or 


2 
x 
y’ = b' +(1- =) 


Because a? and b? are used in the calculation of each point, and because 
they are constant during the execution of this picture, separate variables 
are set aside for each, and calculated only once. A? is called Half_height_ 
squared and b* is Half_width_squared. 


Example 


“TITLE "ELLIPSE - Draw an ellipse centered at 0,0" 
ZIDENT "X1.000" 
PICTURE ellipse (SINGLE Width, Height_1) 
OPTION TYPE = EXPLICIT 
DECLARE LONG CONSTANT Number_of_steps = 60 
DECLARE SINGLE Half_width, & 
Half_height, & 
Half_width_squared, & 
Half_height_squared, & 
Increment, & 
X_pos ,Y_pos 
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Half_height = Height_1/ 2 
Half_width = Width / 2 
Half_height_squared = Half_height * Half_height 
Half_width_squared = Half_width * Half_width 
Increment = Width/Number_of_steps 
I+ 
! Draw the top of the ellipse 
!- 
PLOT LINES -Half_width, 0; 
FOR X_pos = -Half_width + Increment TO Half_width STEP Increment 
Y_pos = SQRT (ABS (Half_height_squared & 
* (1-X_pos*X_pos/Half_width_squared)) ) 

PLOT LINES X_pos, Y_pos; 
NEXT X_pos 
'+ 
! Because the FOR loop above may not exactly terminate 
! at +Half_width due to the imprecision of floating point arithmetic, 
! complete the top half of the ellipse: 
1- 
PLOT LINES Half_width, 0; 
1+ 
! Draw the bottom of the ellipse 
1- 
FOR X_pos = Half_width - Increment TO -Half_width STEP -Increment 

Y_pos = - SQRT (ABS(Half_height_squared & 

* (1-X_pos*X_pos/Half_width_squared) )) 

PLOT LINES X_pos, Y_pos; 
NEXT X_pos 
1+ 
! Because the FOR loop above may not exactly terminate 
! at -Half_width because of the imprecision of floating point arithmetic, 
! complete the bottom half of the ellipse: 
!- 
PLOT LINES -Half_width, 0 

END PICTURE 


You must supply values for the width and height of the ellipse with the 
DRAW statement. The following example invokes the picture ellipse four 
times. 
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Example 


PROGRAM call_ellipses 
EXTERNAL PICTURE ellipse (SINGLE, SINGLE) 
SET WINDOW -0.5,0.5,-0.5,0.5 
DRAW ellipse(0.1,0.25) 
DRAW ellipse(0.25,0.7) 
DRAW ellipse(0.5,0.35) 
DRAW ellipse(0.9,0.15) 
END PROGRAM 


Output 


(ES 


a 
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Window and viewport boundaries are set in the main program before 
pictures are invoked. You cannot set the boundaries of windows and 

viewports or alter the clipping status within a picture definition. The 

following statements are invalid when used within a picture definition: 
— SET WINDOW 

— SET VIEWPORT 

— SET CLIP 

— SET TRANSFORMATION 

— SET DEVICE WINDOW 


6-6 Creating Complex Images 


— SET DEVICE VIEWPORT 
— SET INPUT PRIORITY 


.1.2 Pictures Within Pictures 


A picture definition can contain DRAW statements to invoke other pic- 
tures, as shown in the following example. Note that the picture room is 
declared with the EXTERNAL statement in the picture house. 


Example 


PICTURE house 
EXTERNAL PICTURE room 


DRAW room 
END PICTURE 


PICTURE room 


END PICTURE 


The following picture, face, declares three other pictures with the 
EXTERNAL statement, then invokes each of the pictures in turn. 


Example 


PICTURE face 
EXTERNAL PICTURE head, eyes, mouth 
DRAW head 
DRAW eyes 
DRAW mouth 
END PICTURE 


PICTURE head 
DECLARE LONG CONSTANT npoints = 40 
DECLARE SINGLE turn,increment,radius, & 
LONG loop_count 
DIM SINGLE xs(40), ys(40) 


Creating Complex Images 6-7 


increment = 2 * PI/npoints 

turn = 0 

radius = 0.5 

FOR loop_count = 0% TO (npoints - 1%) 
xs(loop_count) = COS (turn) * radius + 0.5 
ys(loop_count) = SIN (turn) * radius + 0.5 
turn = turn + increment 

NEXT loop_count 

xs(npoints) = xs (0) 

ys(npoints) = ys(0) 

MAT PLOT LINES xs,ys 

END PICTURE 


PICTURE EYES 

SET POINT STYLE 4 

PLOT POINTS 0.35,0.65; 0.65,0.65 
END PICTURE 


PICTURE MOUTH 
DECLARE LONG counter 
DIM SINGLE mouth_x (6) ,mouth_y(6) 
DATA 0.25,0.34,0.4,0.5,0.6,0.66,0.75, & 
0.425,0.36,0.325,0.324,0.325,0.365,0.425 
READ mouth_x(counter) FOR counter = 0 TO 6 
READ mouth_y(counter) FOR counter = 0 TO 6 
MAT PLOT LINES mouth_x,mouth_y 
END PICTURE 


When invoked with the DRAW statement, this picture creates one face: 


Example 


EXTERNAL PICTURE face 
SET WINDOW 0,1,0,1 
DRAW face 

END 
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Output 
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1.3 Recursive Pictures 


A picture definition can be recursive; that is, a picture definition can 
include a DRAW statement that invokes the same picture again. For 
recursive pictures, the picture must be declared with the EXTERNAL 
statement within the picture definition as well as in the program unit that 
first calls the picture. The following picture defines a tunnel made up of 
concentric circles. The picture invokes itself with a smaller radius each 
time. After the requested number of circles is drawn, the EXIT PICTURE 
statement terminates execution of the picture. 
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OPTION ANGLE = DEGREES 

EXTERNAL PICTURE tunnel(SINGLE , ,LONG) 
SET WINDOW -0.5,0.5,-0.5,0.5 

DRAW tunnel (0.05,0.03,11) 

END 


PICTURE tunnel (SINGLE radius,variation,LONG counter) 
OPTION TYPE = EXPLICIT 
DECLARE LONG loop_count, & 
SINGLE turn,increment ,x,y 
DECLARE LONG CONSTANT npoints = 40 
DIM SINGLE xs(npoints), ys(npoints) 
EXTERNAL PICTURE tunnel(SINGLE , ,LONG) 


increment = 2+*PI/npoints 
turn = 0 
FOR loop_count = 0% TO npoints - 1% 
xs(loop_count) = COS (turn) * radius 
ys(loop_count) = SIN (turn) * radius 
turn = turn + increment 
NEXT loop_count 
xs(npoints) = xs(0) 
ys(npoints) = ys(0) 
MAT PLOT LINES xs,ys 


IF counter > 1 
THEN DRAW tunnel(radius + variation, variation, (counter-1)) 
END IF 
END PICTURE 
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Output 
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The following example adds code to make the picture ellipse from 
Section 6.1.1 recursive. The picture creates 18 ellipses. With each 
invocation, the value of Height_1 is increased and the value of width 
is decreased. 


Example 


PROGRAM pattern_ellipses 
EXTERNAL PICTURE recursive_ellipse (SINGLE, SINGLE, LONG) 
SET WINDOW -0.5,0.5,-0.5,0.5 
DRAW recursive_ellipse(0.9,0.1,0) 

END PROGRAM 
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PICTURE recursive_ellipse(SINGLE width, Height_1,LONG counter) 
OPTION TYPE = EXPLICIT 
DECLARE LONG CONSTANT Number_of_steps 
DECLARE SINGLE Half_width, 
Half_height, 
Half_width_squared, 
Half_height_squared, 
Increment, 
X_pos,Y_pos 
Half_height = Height_1/ 2 
Half_width = width / 2 
Half_height_squared = Half_height * Half_height 
Half_width_squared = Half_width * Half_width 
Increment = Width/Number_of_steps 
PLOT LINES -Half_width, 0; 
FOR X_pos = -Half_width + Increment TO Half_width STEP Increment 
Y_pos = SQRT (ABS (Half_height_squared * & 
(1-X_pos+X_pos/Half_width_squared) ) ) 
PLOT LINES X_pos, Y_pos; 
NEXT X_pos 
PLOT LINES Half_width, 0; 


60 


Serre il 


FOR X_pos = Half_width - Increment TO -Half_width STEP -Increment 
Y_pos = -SQRT (ABS (Half_height_squared * & 
(1-X_pos*X_pos/Half_width_squared) )) 
PLOT LINES X_pos, Y_pos; 
NEXT X_pos 
PLOT LINES -Half_width, 0 
t+ 
!Additional code for recursion 
t- 
IF counter < 17 
THEN 
width = width - 0.05 
Height_1 = Height_i + 0.05 
IF counter > 12 
THEN SET LINE COLOR 3 
ELSE IF counter > 6 
THEN SET LINE COLOR 2 
END IF 
END IF 
DRAW recursive_ellipse(width,Height_1,(counter + 1)) 
ELSE 
EXIT PICTURE 
END IF 
END PICTURE 
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Output 





2 Invoking Pictures with Transformation Functions 


The examples so far have used a simple form of the DRAW statement 
to invoke a picture. The DRAW statement can also include optional 
transformation functions. These optional functions allow you to control 
the positioning of the picture. 


To change an image in size, shape, or position, you usually define trans- 
formations as explained in Chapter 5. For instance, you can change 

the position of an image by altering the window or viewport settings. 
However, when the image is defined in a picture, you can transform the 
image with VAX BASIC built-in functions. When you include a transfor- 
mation function in the DRAW statement, the picture is transformed during 
execution. The built-in transformation functions include: 


e SHIFT 
e SCALE 
e ROTATE 
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e SHEAR 
e TRANSFORM 


In addition, you can define your own transformation functions to use witl 
the DRAW statement. See Section 6.3 for more information. 


Each transformation function has a unique effect on the points plotted 
by output statements within the picture definition. These transformation 
functions affect points only in PLOT and MAT PLOT statements; points 
in GRAPH and MAT GRAPH statements within a picture definition are 
not affected by the transformation functions included with the DRAW 
statement. Therefore, when you want output statements to be affected 
by the transformation functions, use PLOT and MAT PLOT statements in 
subprograms. See Chapter 7 for information about accepting input during 
execution of a picture. 


When you know that transformation functions will not be used, it is more 
efficient to use GRAPH statements rather than PLOT statements inside 
picture definitions. 


Note that when text is drawn within a picture, text attributes, such as 
the starting point and the height, are not affected by the transformation 
functions in a DRAW statement; for more information on transforming tex 
output, see the TRANSFORM function in Chapter 9. 


The following sections describe the effects of each of these transformatior 
functions. 


6.2.1 Shifting Pictures 


You can move or shift pictures by including the transformation function 
SHIFT with the DRAW statement. The amounts of shifting you want to 
apply to each of the x- and y-coordinates in an image are supplied as 
arguments to the SHIFT function. The x- and y-coordinates of the points 
are moved or shifted by the amounts specified, as in this example: 


DRAW boxes WITH SHIFT(move_x,move_y) 


The value of move_x is added to each x-coordinate for output statements 
specified in the picture so that the new value of the x-coordinate is 

x + move_x. The value of move_y is added to each y-coordinate so 

that the resulting value for the y-coordinate is y + move_y. 
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In the following example, the image of a triangle is first drawn in red 
without any transformation function applied. The second invocation 
shifts the triangle to the right and is displayed in blue. The value of the 
y-coordinates is not altered in the blue triangle because the value for 
move_y is zero. In the third DRAW statement, the color is changed to 
green. Both the x- and y-coordinates are changed and the triangle is 
shifted to the right and moved up. The program uses the default world 
viewport, but sets the world window to 0,100,0,100 before the picture is 
invoked. 


OPTION TYPE = EXPLICIT 

EXTERNAL PICTURE triangle 

DECLARE LONG CONSTANT red = 2,blue = 3,green = 1 
DECLARE SINGLE move_x,move_y 


SET WINDOW 0,100,0,100 

SET LINE COLOR red 

DRAW triangle 

move_x = 30 

move_y = 0 

SET LINE COLOR blue 

DRAW triangle WITH SHIFT(move_x,move_y) 
move_x = 50 

move_y = 35 

SET LINE COLOR green 

DRAW triangle WITH SHIFT(move_x,move_y) 
END 


PICTURE triangle 
PLOT LINES 10,10; 25,50; 35,10; 10,10 
END PICTURE 
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Output 





In the following example, the image of a swan is defined in a picture. Th 
picture is invoked seven times with the SHIFT function. Unlike the pictu 
swan in Chapter 5, this picture uses PLOT statements rather than GRAPI 
statements. The window is set to -200,200,-200,200 before the picture is 
invoked. 
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Example 


PICTURE swan 
OPTION TYPE = EXPLICIT 
DECLARE LONG counter 
DIM SINGLE x_array(98) ,y_array(98), 
mark_x(3) ,mark_y(3), 
eye_x(2) ,eye_y(2), 
wing_area_x(28) ,wing_area_y(28) 
Outline_data: 


& & & 


DATA 82,80.5,80,80.5,75,81,72,81.5,70,83.5,68,84,65,84.5, & 
63 ,83 ,61,82,60.5,80,60.55,78,62.5,75,64,70,66.5,67,70,62.5, & 
72,60,75,57,78,54,80,50,82.5,46,84,40,86.5,30,87,24.5,87,20, & 
86,17.5,83.5,13.5,82,12,80,11.5,77,10,70,9,65,9,60,9.2,53,10, & 
50,10.5,40,12,35,14,30,18,27,20,20,27.5,14,36,12,40,8.5,50,8, & 
59,10,52.5,14,48,20,45,17,50,16.75,57,20,60,18,61.5,20,67,27, & 
75,27.5,72,37,85,36,80,34,75,32.25,70,32,65,32.25,60,32.35, & 
58,34,53,35,50,38,45,40,41,43.5,38,48,34,52,32.5,60,31,63,32, & 
69.5,35.5,70.5,37,72,40,70.5,43,69.5,47,68.5,50,65.5,55,62.5, & 
60 ,60,65,57.5,70,55,75,54,80,64.25,83,54,84.5,55,87,59,90,60, & 
91 ,63,92.25,66.5,93,68,92.75,70,92,71.5,91,73,89.5,74,87,75.5, & 
85 ,78 ,84,80,82,82,82,80,80.5,82,80.5 


Wing_area_data: 


DATA 32.35,58,34,53,35,50,38,45,40,41,43.5,38,48,34,52,32.5, 
60, 31,63,32,69.5,35.5,70.5,37,32.35,58,30.05,50,28,42,27.5, 
44.5,28.5,30,30,24,31.5,20,35,14,40,12,45,13,50,14,53,15, 


58.5,17.5,61,19,64.5,22,69,30,70.5,37 


Head_mark_data: 
DATA 73,87,70,86,73,85,73.15,86,67 ,89,69,88,70.5,90 


& & & 


READ x_array(counter) ,y_array(counter) FOR counter = 0% TO 98% 

READ wing_area_x(counter) ,wing_area_y(counter) FOR counter = 0% TO 28% 
READ mark_x(counter) ,mark_y(counter) FOR counter = 0% TO 3% 

READ eye_x(counter), eye_y(counter) FOR counter = 0% TO 2% 


Display_the_swan: 
SET LINE COLOR 3% 
SET LINE STYLE 1 
MAT PLOT LINES x_array,y_array 
SET AREA STYLE "PATTERN" 
MAT PLOT AREA : wing_area_x,wing_area_y 
MAT PLOT AREA mark_x,mark_y 
SET LINE COLOR 2% 
MAT PLOT LINES eye_x,eye_y 
END PICTURE 


PROGRAM swimming_swans 
EXTERNAL PICTURE swan 


SET WINDOW , TRAN 1 : -200,200,-200,200 


DRAW swan WITH SHIFT(50,0) 
DRAW swan WITH SHIFT(-25,0) 
DRAW swan WITH SHIFT(-100,0) 
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DRAW swan WITH SHIFT(-135,-100) 
DRAW swan WITH SHIFT(-60, -100) 
DRAW swan WITH SHIFT(15,-100) 
DRAW swan WITH SHIFT(90, -100) 
f+ 


!Adjust the text height for the new window 
t- 


SET TEXT HEIGHT 10% 


GRAPH TEXT AT -50,-5 : “Seven Swans A-Swimming" 
END PROGRAM 


Output 





If the picture swan had used MAT GRAPH statements instead of MAT 
PLOT statements, the image of the swan would not have been shifted at 
all. Instead, each swan would have been displayed in exactly the same 
position as in the first invocation. 
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2.2 Scaling Pictures 


The SCALE function allows you to increase or decrease the size of the 
image produced by a picture. You can scale the width and the height of 
an image by a scale factor you supply. The following statement supplies 
arguments for both the height and the width with SCALE. 


DRAW picture_name WITH SCALE(2,3) 


This DRAW statement multiplies each x-coordinate in the PLOT statement 
of the picture by 2. Each y-coordinate is multiplied by 3. The effect of 
this statement and other DRAW WITH SCALE statements are illustrated 
in the following example. The picture triangle is invoked at first with no 
transformation function. The second DRAW statement scales only the 
x-coordinates (displayed in red). The third invocation of the triangle scales 
only the y-coordinates (displayed in blue). The final invocation of the 
triangle scales both the x- and y-coordinates. Notice that the triangle is 
not shifted. An example in Section 6.2.5 demonstrates how to combine 
the SHIFT and SCALE functions. 


Example 


OPTION TYPE = EXPLICIT 

EXTERNAL PICTURE triangle 

DECLARE LONG CONSTANT red = 2, & 
blue = 3, green = 1 

SET WINDOW 0,100,0,100 

DRAW triangle 

SET LINE COLOR red 

DRAW triangle WITH SCALE(2,1) 

SET LINE COLOR blue 

DRAW triangle WITH SCALE(1,2) 

SET LINE COLOR green 

DRAW triangle WITH SCALE(2) 

END 
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Output 
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The following example illustrates the effect of reducing the y-coordinates 
while leaving the x-coordinates unchanged. The DRAW statement invok: 
the picture face, multiplies each x-coordinate by 1 (leaving it unchanged) 
and divides each y-coordinate by 2. 


Example 


EXTERNAL PICTURE face 

SET WINDOW 0,1,0,1 

DRAW face WITH SCALE(1,0.5) 
END 
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Output 
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6.2.3 Rotating Pictures 


Images defined in picture definitions can be rotated in a counterclockwise 
direction about the point of origin (point 0,0). You specify the amount 
of rotation as an argument to the ROTATE function. The amount of 
rotation can be in radians or degrees, according to the OPTION ANGLE 
statement for the program unit. Negative values cause rotation in a 
clockwise direction. The following DRAW statement invokes a picture 
with a rotation of 15° in a counterclockwise direction. 


OPTION ANGLE = DEGREES 
DRAW picture_name WITH ROTATE(15) 


The following program draws the picture circle 24 times with an increasing 
value for the rotation. The world window is set to place the point 0,0 in 
the center of the window. The picture is rotated about the center point. 
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Example 


PROGRAM call_circles 

OPTION ANGLE = DEGREES 

OPTION TYPE = EXPLICIT 

DECLARE LONG loop 

EXTERNAL PICTURE circle(SINGLE) 
SET WINDOW -1,1,-1,1 


FOR loop = 1 TO 24 

t+ 

!Draw circle with radius 0.2 

f- 

DRAW circle(0.2) WITH ROTATE(15 * loop) 
NEXT loop 
END PROGRAM 


PICTURE circle(SINGLE radius) 
OPTION TYPE = EXPLICIT 
DECLARE SINGLE angle 
DECLARE LONG CONSTANT npoints = 40 
DECLARE SINGLE CONSTANT increment = 2*PI/npoints 
DECLARE LONG loop_count 
DIM SINGLE xs(40), ys(40) 


angle = 0 

FOR loop_count = 0% TO npoints - 1% 
xs(loop_count) = COS (angle) * radius + 0.5 
ys(loop_count) = SIN (angle) * radius + 0.5 
angle = angle + increment 

NEXT loop_count 

xs(npoints) = xs(0) 

ys(npoints) = ys(0) 

MAT PLOT LINES xs,ys 

END PICTURE 
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The point of origin need not be within the world window. For example, 
an image in the window 25,50,25,50 can be rotated about the point 0,0 
even though this point is not in the window. 


Note that pictures can be rotated about any point you choose. The 
following statement rotates the picture tryit about the point x,y. 


DRAW tryit WITH SHIFT(-x,-y) * ROTATE(angle) * SHIFT(x,y) 


The examples in this section rotate pictures about the point of origin. See 
the DRAW statement in Chapter 9 for an example of rotating a picture 
about other points. 
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6.2.4 Shearing Pictures 


The SHEAR function allows you to skew the coordinates of an image so 
that the image appears to tilt or lean over. The exact placement depends 
on the argument you supply with SHEAR and the relative position of the 
point of origin (0,0). You can supply the argument in either degrees or 
radians, depending on the option you specify with the OPTION ANGLE 
statement. The following statement changes the coordinates of a point x,y 
to the coordinates (x + y * TAN(25)),y. 


OPTION ANGLE = DEGREES 
DRAW picture_name WITH SHEAR(25) 


The following example uses SHEAR to skew the picture ball (a circle) 
several times to illustrate the effects of various arguments. Notice that 
unlike the ROTATE function, SHEAR does not change the values of the 
y-coordinates. 


Example 


PROGRAM Spring 

OPTION ANGLE = DEGREES 
EXTERNAL PICTURE coil (SINGLE) 
DECLARE LONG loop_count 


FOR loop_count = 0% to 5% 
!Draw coil with radius of 0.15 
DRAW coil(0.15) WITH SHEAR(10 * loop_count) 
NEXT loop_count 
END PROGRAM 
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Output 
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5.2.5 Combining Transformations 


You can invoke a picture with more than one transformation function. To 
use more than one transformation function with the DRAW statement, 
separate the functions with an asterisk (*). For instance, the following 
DRAW statements each use a combination of two transformation functions: 


Example 


DRAW face WITH SHEAR(30) * SCALE(1,2) 
DRAW face WITH SHIFT(3,0.5) * SCALE (2) 


Transformation functions are not associative; therefore, the order of 

the functions on the DRAW statement is important when you combine 
transformations. For instance, SHIFT * SCALE does not produce the same 
new coordinates as SCALE * SHIFT. This is comparable to the importance 
of the order of operations in a numeric expression. 


Creating Complex Images 6-25 


In Section 6.2.2, the scaled triangles are displayed without any shifting, 
making the individual triangles difficult to differentiate. The following 
example draws the picture triangle by combining the SHIFT and SCALE 
functions. 


In the following example, the picture triangle is invoked three times with 
the DRAW statement as follows: 


1. With no transformation 
2. With SCALE(2) * SHIFT(20,0) 
3. With SHIFT(20,0) *« SCALE(2) 


PROGRAM draw_triangles 
EXTERNAL PICTURE triangle 
SET WINDOW, TRAN 1 : 0,100,0,100 
SET TEXT HEIGHT 3 
t+ 
!Triangle 1 in output 
!- 
DRAW triangle 
GRAPH TEXT AT 15,10 : "i" 
1+ 
!'Triangle 2 in output 
t- 
DRAW triangle WITH SCALE(2) * SHIFT(20,0) 
GRAPH TEXT AT 50,65 : "2" 
1+ 
!Triangle 3 in output 
t- 
DRAW triangle WITH SHIFT(20,0) * SCALE(2) 
GRAPH TEXT AT 70,65 : "3" 
END PROGRAM 
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Output 
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The following example combines the ROTATE and SCALE transformation 
functions. Each invocation of the picture square increases the size of the 
square and turns the square by an additional 0.25 radians. The window is 
set to -1,1,-1,1 so that the point of origin is in the center of the screen. 


Example 


PROGRAM call_square 
OPTION TYPE = EXPLICIT 
OPTION ANGLE = RADIANS 
EXTERNAL PICTURE square 
DECLARE SINGLE counter 
SET WINDOW -1,1,-1,1 


FOR counter = 1 TO 10 STEP 0.25 
IF color_var < 3 
THEN color_var = color_var + 1 
ELSE color_var = 1 
END IF 
DRAW square WITH ROTATE(counter) * SCALE(counter,counter) 
NEXT counter 
END PROGRAM 
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PICTURE square 


PLOT LINES : -0.05, 0.05; & 
0.05, 0.05; & 
0.05,-0.05; & 
-0.05,-0.05; & 
-0.05,0.05 

END PICTURE 

Output 





The following example shifts and rotates the picture swan counterclock- 
wise about the center point of the world window. Each invocation of the 
picture rotates the image of the swan 51° from the previous invocation. 
The point of origin is at the center of the screen. 


Example 


OPTION TYPE = EXPLICIT 

OPTION ANGLE = DEGREES 

EXTERNAL PICTURE swan 

DECLARE SINGLE CONSTANT turn = 51 
DECLARE LONG loop 


SET WINDOW , TRAN 1 : -200,200,-200,200 


FOR loop = 1 TO 7 
DRAW swan WITH SHIFT(21,21) * ROTATE(turn * loop) 
NEXT loop 
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SET TEXT HEIGHT 12% 

GRAPH TEXT AT -40,0 : "Seven Swans" 
GRAPH TEXT AT -38,-12 : "A-Spinning" 
END 


Output 





Nested picture invocations can also have transformation functions. Such 
nested picture definitions can lead to an accumulation of transformations. 
There is no limit to the number of levels you can nest pictures; however, 
nesting several levels deep makes your program extremely difficult to read 
or debug. 


When picture invocations are nested within other pictures, the original 
transformation function applies throughout the execution of the picture 
in addition to any other transformation function used. For instance, the 
following picture definition includes invocations using transformation 
functions as well as a recursive picture invocation. 
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Example 


PICTURE outside 
EXTERNAL PICTURE insidei, inside2, outside 
DECLARE SINGLE angle_var,move_x,move_y 
DECLARE LONG counter 


counter = 1 
DRAW insidei 
DRAW inside2 WITH SHEAR(angle_var) 
IF counter > 10 
THEN DRAW outside WITH SHIFT(move_x,move_y) 
END IF 
counter = counter + 1 
END PICTURE 


PROGRAM calling 
EXTERNAL PICTURE outside 
DRAW outside WITH SHIFT(1,0) 
END PROGRAM 


When the picture outside is invoked with the transformation function 
SHIFT, picture inside1 and inside2 are invoked with an implicit SHIFT 
function. Picture inside2 includes a SHEAR function, which is applied in 
addition to the invocation with SHIFT. 


The recursive call of picture outside also includes a transformation func- 
tion. The original invocation with the transformation function SHIFT is 
still applied in addition to the SHIFT function in the recursive call. Each 
recursive invocation builds on the accumulated transformations up to tha 
point. 


The following section discusses how to define your own transformation 
matrices. If you are content with the transformation functions VAX BASI 
provides, then move on now to Chapter 7, which discusses different way 
of supplying graphics input to your programs. 


6.3 Defining Your Own Transformation Matrices 


When you use a transformation function, each point plotted in the pictur 
is transformed into a point with new coordinates. VAX BASIC translates 
each point by multiplying it by a 4 by 4 matrix. The transformation 
functions described in this chapter each represent a particular 4 by 4 
matrix for the transformation of a point. The following chart displays the 
matrix represented by each VAX BASIC transformation function. Note 
that these matrices actually have 5 rows and 5 columns; the elements in 
row and column zero are used by VAX BASIC and are not shown here. 
The matrices have lower bounds of zero and upper bounds of 4. 
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Figure 6-1: Matrices for VAX BASIC Transformation 


Functions 
SHIFT(A,B) SCALE(A,B) SCALE(A) 
1000 A000 A000 
0100 0B00 0A00 
0010 0010 0010 
ABO 1 0001 0001 
ROTATE(A) SHEAR(A) 
COS(A) SIN(A) 00 1 000 
-SIN(A) COS(A) 0 0 TAN(A) 100 
0 0 10 0 010 
0 0 01 0 001 
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You can supply your own matrix with the DRAW statement in place of 
any of the VAX BASIC transformation functions. To do this, first, you 
can declare a two-dimensional array and initialize the elements to be 
zero. The matrix must be zero-based and have upper bounds of 4 in both 
directions. In addition, matrices cannot be record arrays. Next, assign the 
values you want in the appropriate matrix elements. You should not use 
elements in row and column zero because VAX BASIC uses these elements 
during the multiplication of these matrices. The following code sets up a 
matrix that is equivalent to a transformation of SHIFT(A,B): 


DECLARE SINGLE A,B, & 
LONG row,col 

DIM SINGLE shift_matrix(4,4) 

FOR row = 1 TO 4 
FOR col = 1 TO 4 
shift_matrix(row,col) = 0 
NEXT col 

NEXT row 


shift_matrix(1,1) 
shift_matrix(2,2) 
shift_matrix(3,3) 
shift_matrix(4,4) 
shift_matrix(4,1) 
shift_matrix(4,2) 


Wr eee 
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The following two statements are now equivalent: 


DRAW picture_name WITH shift_matrix 
DRAW picture_name WITH SHIFT(A,B) 


You can define your own matrices and thereby create your own trans- 
formation functions. For instance, for frequently used combinations of 
transformations, you can define a new 4 by 4 matrix and use it in the 
DRAW statement as an alternative to combining transformation functions. 
To do this, use the MAT statement. The following example defines a 
new matrix that combines the transformation functions SCALE(A) and 
ROTATE(B): 


Example 


OPTION TYPE = EXPLICIT 

OPTION ANGLE =- DEGREES 

EXTERNAL PICTURE kite 

DECLARE SINGLE A,B 

DIM SINGLE new_matrix(4,4) 

MAT new_matrix = SCALE(A) * ROTATE(B) 
DRAW kite WITH new_matrix 

END 


Applying this matrix with the DRAW statement scales a set of x- and 
y-coordinates by the value of A, and it also rotates the set of points by 
B degrees. 


The following example invokes the picture face with a variety of transfor- 
mation functions. The MAT statement is used to create new matrices buili 
on the previous position of the face. 


Example 


!Invoking program 
PROGRAM party_crowd 
OPTION TYPE = EXPLICIT 
OPTION ANGLE = DEGREES 
EXTERNAL PICTURE face 
DIM SINGLE next_face(4,4) ,temp_face(4,4) 
SET WINDOW 0,5,0,5 
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I+ 

!Draw the party crowd 

t= 

SET LINE COLOR 3 

DRAW face WITH SCALE(1.25,3.25) 

SET LINE COLOR 2 

DRAW face WITH SHIFT(1.5,1.25) 

MAT next_face = SHIFT(1.5,1.25) * SHEAR(15) 

DRAW face WITH next_face 

MAT temp_face = next_face * SHIFT(2,1) 

MAT next_face = temp_face * SHEAR(-30) 

SET LINE COLOR 3 

DRAW face WITH next_face 

MAT temp_face = next_face * SHIFT(-0.5,1.5) 

MAT next_face = temp_face 

DRAW face WITH next_face 

MAT temp_face = next_face * SHEAR(30) 

MAT next_face = temp_face * SCALE(0.75,0.75) * SHIFT(-0.5,1) 

DRAW face WITH next_face 

MAT temp_face = next_face 

MAT next_face = temp_face * SHIFT(0,-3) * SCALE(1,0.75) 

SET LINE COLOR 2 

DRAW face WITH next_face 

MAT temp_face = next_face 

MAT next_face = temp_face * SHIFT(-2,2) 

DRAW face WITH next_face 

MAT temp_face = next_face 

MAT next_face = temp_face * SHIFT(i1,1) * SCALE(0.75,0.75) 

DRAW face WITH next_face 

MAT temp_face = next_face * SHEAR(25) 

MAT next_face = temp_face * SHIFT(1.5,-2.5) * SCALE(1,1.25) 

SET LINE COLOR 3 

DRAW face WITH next_face 

t+ 

!No cumulative matrix used for this one 

1- 

SET LINE COLOR 2 

DRAW face WITH ROTATE(300) * SHEAR(60) & 
* SHIFT(1.25,0.75) 


SET TEXT HEIGHT 0.25 
GRAPH TEXT AT 0.25,3.4 : "Your BASIC Party Crowd" 
END PROGRAM 


PICTURE face 
OPTION ANGLE = DEGREES 
EXTERNAL PICTURE head ,mouth,eyes 
DRAW head 
DRAW eyes 
DRAW mouth 
END PICTURE 
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PICTURE head 

OPTION TYPE = EXPLICIT 

DECLARE LONG CONSTANT npoints = 40 

DECLARE SINGLE CONSTANT increment = 2*PI/npoints, 
radius = 0.5 

DECLARE SINGLE angle, 

LONG loop 
DIM SINGLE xs(40), ys(40) 


angle = 0 

FOR loop_count = 0% TO npoints - 1% 
x = COS(angle) * radius + 0.5 
y = SIN(angle) * radius + 0.5 
xs(loop_count) = x 
ys(loop_count) = 
angle = angle + increment 

NEXT loop_count 


xs(npoints) = xs(0) 

ys(npoints) = ys(0) 

MAT PLOT LINES xs,ys 
END PICTURE 


PICTURE mouth 
DECLARE SINGLE nouth_x(6),mouth_y(6), & 
LONG loop 
DATA 0.25,0.425,0.34,0.36,0.4,0.325, & 
0.5,0.324,0.6,0.325,0.66,0.365, & 
0.75,0.425 
READ mouth_x(loop) ,mouth_y(loop) FOR loop = 0% TO 6% 
MAT PLOT LINES mouth.x,mouth_y 
END PICTURE 


PICTURE eyes 

SET POINT STYLE 4 

PLOT POINTS 0.35,0.65; 0.65,0.65 
END PICTURE 
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Output 
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VAX BASIC provides an additional transformation function, TRANSFORM. 
When used within nested picture invocations, the TRANSFORM function 
returns the cumulative matrix for all current transformations. Like the 
other transformation functions, TRANSFORM can be used on the right- 
hand side of a MAT statement or as a transformation function in the 
DRAW statement. 


A picture drawn from within a picture automatically inherits the transfor- 
mations for the outer picture as well as the transformations specified in 
the current invocation. Therefore, using the TRANSFORM function in a 
DRAW statement causes the picture to be invoked with twice the current 
transformation. 


In the following example, the picture food is invoked with a transformation 
of SCALE(2) * SCALE(2). 
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Example 


PROGRAM call_tray 
EXTERNAL PICTURE tray 
DRAW tray WITH SCALE(2) 

END PROGRAM 


PICTURE tray 
OPTION ANGLE = DEGREES 
EXTERNAL PICTURE food 
DRAW food WITH TRANSFORM 
END PICTURE 


In the following example, the picture three is invoked with the DRAW 
statement using the TRANSFORM function. At the time of invocation, 
TRANSFORM contains values equivalent to ROTATE(45) * SHIFT(1,0); 
therefore, three will be invoked with the equivalent of ROTATE(45) * 
SHIFT(1,0) * ROTATE(45) * SHIFT(1,0). 


Example 


OPTION ANGLE = DEGREES 

OPTION TYPE = EXPLICIT 

EXTERNAL PICTURE one, two, three 
DRAW one WITH SHIFT(1,0) 

END 


PICTURE one 

EXTERNAL two 

DRAW two WITH ROTATE(45) 
END PICTURE 


PICTURE two 

EXTERNAL three 

DRAW three WITH TRANSFORM 
END PICTURE 


You can also use the TRANSFORM function to define your own matrices 
for the DRAW statement. For more examples, see the DRAW statement 
and the TRANSFORM function in the reference section of this manual. 


When used outside of pictures, TRANSFORM returns the identity matrix, 
which has no effect on a graphics display. Like other transformation 
functions, TRANSFORM affects only objects drawn with PLOT statements 
not GRAPH statements. 
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4 Summary 


The statements and topics described in this chapter include: 


e Pictures (PICTURE subprograms) 
e Invoking pictures with DRAW 


e Invoking pictures with the transformation functions SHIFT, SCALE, 
ROTATE, SHEAR, and TRANSFORM 


e Defining your own transformation matrices 
So far, data for the examples has been supplied with DATA and READ 


statements or supplied as constants. The following chapter describes 
interactive means to supply graphics data. 
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Chapter 7 


Graphics Input 





VAX BASIC provides input statements so that a user! can interact with an 
application program. These statements enable a user to supply input to an 
application program at run time. 


Many of the statements in this chapter can include an optional device 
identification number as a parameter. The device identification number is 
a number you supply to distinguish between devices when your program 
uses several devices. If you use a VAXstation, device identification num- 
bers can be used to address different workstation windows. The programs 
in this chapter use only one device, or in the case of a VAXstation II, one 
workstation window; therefore, the statements do not include the optional 
device identification. For more information about using multiple devices, 
see Chapter 8. 


The exact number and form of prompts, triggers, visual indicators, and 
echoes supported by each type of input varies with each device and is 
beyond the scope of this manual. Refer to the VAX GKS documentation 
and the hardware documentation for information about a particular device. 


1 In this chapter the term “user” is synonymous with a program operator; the word “you” refers to the 
programmer. 
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7.1 Input Types 


There are five different types of graphics input described in the following 
sections. For example, input could be a choice from a menu, the coordi- 
nates of a point, a series of points, a string, or a numeric value; you mus 
specify the type of input you want in your program. The five types of 
input are known in VAX BASIC as: | 


e CHOICE 

¢ POINT 

¢ MULTIPOINT 
e STRING 

e VALUE 


Figure 7-1 illustrates the form of the different input types. 


Figure 7—1: Types of Graphics Input 
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7.1.1 CHOICE input 


You request CHOICE data when you want a user to choose an item 

from a menu you supply. When CHOICE input is requested, the user is 
presented with a menu of items. The default response is emphasized in 
some way, usually with highlighting. The user can choose any item on 
the menu by moving the cursor in some manner. To select an item, the 
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user presses the RETURN key, or possibly a mouse button. Figure 7-2 
illustrates the default screen on a VT240 that is presented to a user when 
CHOICE input is requested. 


Figure 7—2: The Default CHOICE Prompt on a VT240 
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1.2 POINT Input 


You request POINT input when you want a user to supply the position 
of a point. The user can supply a point in various ways, such as by 
positioning a cursor on a display surface with the keyboard arrow keys. 
The methods of entering points vary with each device. 


When POINT input is requested, an initial point is displayed on the user’s 
screen. The initial point is marked by a cross or some other visual marker; 
the actual marker varies with each device. On some devices it is possible 
to modify the prompt to your own design. 


A user can move the prompt freely within the display area until the 
prompt marks the selected point. To enter the selected point as input, the 
user presses RETURN or performs a similar activity (this feature is device 
dependent). 
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7.1.3 MULTIPOINT Input 


You request MULTIPOINT data when you want a user to supply a 
sequence of points. 


When MULTIPOINT input is requested, an initial point, or series of 
points, is marked on the user’s screen. The user can select this initial poin 
or choose other points. The ways to enter points vary with each device. 
For instance, on a VAXstation, points are entered automatically as the use 
moves the mouse. On a VT125, the user enters each point by pressing 
the space bar, then indicates when the input is complete by pressing 
RETURN. When the user moves the prompt to select a second point, a 
line is drawn connecting the first selected point to the second. A line is 
then drawn from the second point to the third, and so on until the series 
of points is complete. All of the points the user selects are connected by 
one continuous line on the screen. 


7.1.4 STRING Input 


You request STRING input when you want a user to supply an individua 
character or an entire text string to your program. 


When STRING input is requested, the user is usually presented with 

an initial string. The user can accept the initial string, or enter a new 
string, or perhaps enter a null string if your program includes a default 
string response. Your program should include string handling functions tc 
analyze the user’s input. 


7.1.5 VALUE Input 
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You request VALUE data when you want a user to supply numeric data 
for your graphics program at run time. 


When VALUE input is requested, the user is presented with a prompt 
similar to that illustrated in Figure 7-3. Depending on the device, the 
upper and lower limits of the acceptable range are displayed and an 
arrow is positioned to indicate the initial response. Some devices display 
the value that is currently selected. The user can select the initial value 
indicated or move the arrow along the scale to select another value withir 
the range presented. The user enters the selected value by pressing 
RETURN. 


Figure 7-3: The Default VALUE Prompt on a VT240 
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The following sections discuss how your program accepts each of the 
graphics input types. To accept all types of input from a user, you can use 
the LOCATE statement. A single point can also be accepted with the GET 
statement, while a series of points can be accepted by the MAT LOCATE 
and MAT GET statements. 


NOTE 


An optional UNIT clause can be included with many of the 
statements used in this chapter. This clause allows you to spec- 
ify an alternative means of supplying the input. For instance, 
the position of points can be entered with the keyboard arrow 
keys or possibly with a mouse. Each of these methods of data 
entry is a different unit. The default unit number for each input 
class is 1. The default unit is used throughout this manual; 
therefore, the UNIT clause is not included in the examples 

in this chapter. For syntax rules related to the UNIT clause, 
see the particular input statement in the reference section of 
this manual. Some devices support more than one unit; for 
information about the units available on a particular device, 


Graphics Input 7-5 


see the documentation for that device as well as the VAX GKS 
documentation. 


7.2 CHOICE Input 


Input statements for CHOICE allow you to: 


e Set up an initial menu 
e Set up an initial choice for the user 
e Accept the user’s actual choice 


7.2.1 Setting the Initial Choice 
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The SET INITIAL CHOICE statement allows you to list the items you 
want displayed on the menu and set an initial menu selection for the use 
The following statement sets up a menu with five possible selections and 
sets the initial selection to the second item in the menu. The menu is not 
displayed until the LOCATE CHOICE statement is executed. 


Example 


DECLARE LONG task 
SET INITIAL CHOICE 
»LIST ("Add" 

» "Update" 
» "Delete" 
» "Read" 
»"Quit") 
<2 


& & & & & & 


Select_menu: 

LOCATE CHOICE task 

ON task GOTO Add_rtn,Update_rtn,Delete_rtn,Read_rtn,Quit & 
OTHERWISE Select_menu 


Output 
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The SET INITIAL CHOICE statement has an optional COUNT clause 
that can be used when you specify an array of strings rather than string 
expressions in the LIST clause. When you declare a string array, you need 
not display all the array elements as items in the menu; you can select a 
subset of the array elements starting with the first element in the array. 
Only the subset of items indicated by the COUNT clause will be displayed 
and the user cannot select an item in the menu that is not displayed on 
the screen. The following example illustrates the use of the COUNT 
clause and supplies an array of strings to the LIST clause. 
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Example 


DECLARE LONG counter 

DECLARE STRING which_letter 

DIM STRING alphabet (65 TO 90) 

alphabet (counter) = CHR$(counter) FOR counter = 65 TO 90 


SET INITIAL CHOICE, LIST alphabet & 
» COUNT 5 & 
> 5 


LOCATE CHOICE which_letter 


Output 











= 
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Subsequent requests for CHOICE input use the values specified in the SET 
INITIAL CHOICE statement unless you specify otherwise with another 
SET INITIAL CHOICE statement. 
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If you do not specify options in a LIST clause, VAX BASIC supplies the 
device dependent defaults. For VAXstation II workstations the default 
menu has two items: “Yes” and “No*. VT125 and VT240 terminals 
provide a five-item menu by default with the options “CHOICE 1”, 
“CHOICE 2”, “CHOICE 3’, “CHOICE 4”, and “CHOICE 5”. 


2.2 Accepting CHOICE Input 


You accept CHOICE input with the LOCATE CHOICE statement. When 
the user makes a selection from a menu, an integer representing that 
item is assigned to a variable you supply with the LOCATE CHOICE 
statement. You set up the menu that is presented to the user with the SET 
INITIAL CHOICE statement; however, the menu is not displayed until the 
LOCATE CHOICE statement is executed. 


In the following example the SET INITIAL CHOICE statement sets up 
a menu of two choices for the user: “Play again” or “Quit”. When the 
LOCATE CHOICE statement is executed, the menu is displayed. “Play 
again” is highlighted as the initial choice; the user’s actual choice is 
assigned to the integer variable game_status in the LOCATE CHOICE 
statement. 
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Example 


DECLARE LONG game_status 

SET INITIAL CHOICE , LIST ("Play again", & 
"Quit") & 
: 1 

LOCATE CHOICE game_status 


Output 
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The initial choice presented to the user can be established in the SET 
INITIAL CHOICE statement, as shown in the previous example. You 
can override this initial choice with an optional INITIAL clause on the 
LOCATE CHOICE statement, as shown in the following example. The 
following example shows a longer menu and shows one method of dealing 
with the user choice in the program. 
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Example 


PROGRAM psyche 

DECLARE LONG behavior 

Locate_choice: 

SET INITIAL CHOICE 

»LIST ("withdrawn" 

» "secretive" 
» "reserved" 
»"well-adjusted" 
» "exuberant" 
, "aggressive" 
» "combative" 
»"Quit program") 
: 3 


RPReerrererereee 


LOCATE CHOICE , INITIAL 4 : behavior 
SELECT behavior 


CASE = i 
GRAPH TEXT AT 0,0.8 : "Do not leave this person alone - ever." 
GRAPH TEXT AT 0,0.7 : "Close curtains on rainy days. Recommend" 
GRAPH TEXT AT 0,0.6 : "constant care. Do NOT prescribe tranquilizers." 
CASE = 2 
GRAPH TEXT AT 0,0.8 : "Recommend intensive group therapy." 
GRAPH TEXT AT 0,0.7 : "Consider anti-depressant drugs." 
GRAPH TEXT AT 0,0.6 : "Confirm medical insurance." 
CASE = 3 
GRAPH TEXT AT 0,0.8 : "Recommend vigorous daily exercise." 
GRAPH TEXT AT 0,0.7 : “Continue group therapy." 
CASE = 4 
GRAPH TEXT AT 0,0.8 : "Make sure this person pays his/her bill," 
GRAPH TEXT AT 0,0.7 : "then recommend ending therapy." 
CASE = 5 
GRAPH TEXT AT 0,0.8 : "Recommend relaxation techniques" 
GRAPH TEXT AT 0,0.7 : "and continue psychotherapy." 
CASE = 6 : 
GRAPH TEXT AT 0,0.8 : "Recommend intensive psychotherapy." 
GRAPH TEXT AT 0,0.7 : "Consider tranquilizers." 
CASE = 7 
GRAPH TEXT AT 0,0.8 : "Do not arm-wrestle with this person." 
GRAPH TEXT AT 0,0.7 : "Recommend sedation and hospitalization." 
GRAPH TEXT AT 0,0.6 : "Discontinue individual therapy unless" 
GRAPH TEXT AT 0,0.5 : "a guard is available at all times." 
CASE = 8 
EXIT PROGRAM 
END SELECT 
END PROGRAM 
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7.3 POINT and MULTIPOINT Input 


You accept POINT input with the LOCATE POINT and GET POINT 
statements, and MULTIPOINT input with the MAT LOCATE POINTS 
and MAT GET POINTS statements. The input statements for POINT and 
MULTIPOINT allow you to: 


e Set up an initial point or series of points for the user 
e¢ Accept the user’s actual input 


7.3.1 Accepting Points with the Default Transformation 


This section describes how to accept input points from a user when 
transformation 1, the default transformation, is the only transformation 
in your program. Transformation 1 is the only transformation when no 
additional transformations are defined in your program, and when no 
SET VIEWPORT or SET WINDOW statements are executed other than for 
redefining the default transformation. 


The LOCATE POINT statement accepts a point the user enters at the ter- 
minal. After execution of the following statement, the world coordinates 
of the user-supplied point are contained in x—coord and y_coord. 


LOCATE POINT x_coord, y_coord 


The MAT LOCATE POINTS statement accepts a series of points that 
the user enters at the terminal into two arrays you have supplied with 
the statement: one array of x-coordinates, and one of y-coordinates. 
After execution of the following statement, the world coordinates of the 
user-supplied points are contained in the arrays x_coords and y_coords. 


DIM SINGLE x_coords(20), y_coords(20) 


MAT LOCATE POINTS x_coords, y_coords 


After the prompt is displayed, the user can accept the initial point or enter 
other points. The methods of entering each point vary with each device. 
For example, with a VT240, a user enters each point by pressing the 
space bar, then indicates when the series of points is complete by pressing 
RETURN. 
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You can specify the world coordinates of an initial point with the optional 
AT clause in both the LOCATE POINT and MAT LOCATE POINTS 
statements. The following statement displays a prompt at the initial 
position 0.2,0.5. The user can accept this initial point, or move the 
prompt and enter the position of another point. After execution, the 
world coordinates of the user-supplied point are assigned to x_coord 

and y_coord. 


LOCATE POINT , AT 0.2,0.5 : x_coord, y_coord 


See Section 7.3.5 for details on how to present a series of points to the 
user. 


An optional COUNT clause in the MAT LOCATE POINTS statement 
allows you to retrieve the number of points actually supplied by the user. 
In the following example, the arrays are set up to hold 26 coordinate 
values; the actual number of points supplied by the user is assigned to the 
variable how_many. 


If the user inputs fewer points than the number of elements in the coordi- 
nate arrays and you plan to use these coordinates for output, you should 
use the COUNT clause to specify the number of array elements to be used 
for the display. 


If a user supplies more points than the number of elements in the arrays, 
the extra points are discarded by VAX BASIC. For instance, in the fol- 
lowing example, if a user enters 30 points, the last four points will be 
discarded. The following example checks whether the user has entered 
extra points. If this is the case, the variable supplied with the COUNT 
clause in the output statement is adjusted to avoid referencing array 
elements that do not exist. 


Example 


DECLARE LONG CONSTANT max_points = 26 
DECLARE LONG how_many 
DIM SINGLE xs(i TO max_points),ys(1 TO max_points) 
GRAPH TEXT AT 0,0.9 : "Enter up to " + STR¢(max_points) + " points" 
MAT LOCATE POINTS , AT .10,.15 & 
,» COUNT how_many & 
: x8, ys 
IF how.many > max_points 
THEN how_many = max_points 
GRAPH TEXT AT 0,0.75: "You have entered too many points." 
GRAPH TEXT AT 0,0.65: "The extra points have been discarded." 


END IF 

SET POINT COLOR 2% 

MAT GRAPH POINTS , COUNT how_many & 
: x8, ys 

END 
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7.3.2 Accepting Points with Multiple Transformations Defined 


When possible, VAX BASIC maps the coordinates of an input point 

to world coordinates using the transformation that is defined for the 
viewport the point falls into. The following sections describe how VAX 
BASIC determines which transformation to use under the following 
circumstances: 


¢ When input points map to an area of NDC space where a single 
viewport is valid 

e When input points map to an area of NDC space where viewports 
overlap 


7.3.2.1 Accepting Points That Map to One Valid Viewport 


When a user enters a point as input, VAX BASIC determines the device 
coordinates of the point entered, then maps the point to NDC space. If 
the input point maps to an area of NDC space where a single viewport 
is valid, the transformation associated with that viewport is used to 
determine the world coordinates of the point. 


In the following example, two transformations are established. 
Transformation 1 redefines the default world viewport and sets the win- 
dow to -100,100,1000,2000. Transformation 2 establishes an additional 
viewport and sets the window to 0,200,-5,5. Notice that these view- 
ports do not overlap and the two viewports together include all of NDC 
space. When a point is input, the point falls into the viewport for either 
transformation 1 or 2 and is interpreted according to the transformation 
associated with the appropriate viewport. Figure 7—4 illustrates these two 
transformations and shows an input point that is interpreted according to 
the viewport for transformation 1. The resulting world coordinates held in 
x and y would be 50,1500. 
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Example 


DECLARE SINGLE x,y 

SET WINDOW , TRAN 1 : -100,100,1000, 2000 
SET VIEWPORT , TRAN 1 : 0,0.5,0,1 

SET WINDOW , TRAN 2 : 0,200,-5,5 

SET VIEWPORT , TRAN 2 : 0.5,1,0,1 


LOCATE POINT x,y 


igure 7—4: An Input Point is Mapped to the Underlying Viewport 
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You can supply an optional integer variable with the LOCATE POINT 
statement to retrieve the transformation number VAX BASIC has used 
to interpret the user-supplied coordinates. For example, the following 
statement instructs VAX BASIC to use the point 0.5,0.5 as the initial point. 
When the user enters a point, the coordinates are assigned to x_coord and 
y—coord. The transformation used to interpret these device coordinates 
into world coordinates is assigned to which_tran. This is useful if you 
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have multiple transformations defined and you want to confirm which 
transformation was actually used. 


Example 
DECLARE SINGLE x_coord,y_coord, & 
LONG which_tran 
SET VIEWPORT , TRAN 1 : 0,0.5,0,1 
SET VIEWPORT , TRAN 2 : 0.5,1,0,1 
LOCATE POINT , AT 0.5,0.5 & 
: x_coord, y.coord , which_tran 


Note that when transformation 1 has been redefined with a viewport 
other than 0,1,0,1 (all of NDC space), it is possible for points to be outsid 
any defined viewport. When this happens, VAX BASIC signals an error. 
In the following example, transformation 1 is redefined to be a portion 
of NDC space. This leaves the remaining portion of NDC space with no 
transformation defined, and it is possible for a user to supply a point that 
falls beyond the boundaries of any defined transformation. 


Example 
SET VIEWPORT , TRAN 1 : 0.5,1,0.5,1 


MAT LOCATE POINTS x_coord, y_coord 


The optional USING TRAN clause on the LOCATE POINT statement 
lets you specify the transformation VAX BASIC should use to display 
the initial point. If you do not include a USING TRAN clause, the 
current transformation is used. In the following example, transformation 
2 is the current transformation when the LOCATE POINT statement is 
executed. However, the USING TRAN clause specifies that transformatio: 
1 should be used to display the initial point regardless of the fact that 
transformation 2 is the current transformation. The USING TRAN clause 
affects only the display of the initial point; the user-supplied coordinates 
are transformed with the current transformation. 
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Example 
DECLARE SINGLE x,y 


SET VIEWPORT , TRAN 1 : 0.5,1,0.5,1 
SET VIEWPORT , TRAN 2 : 0,0.5,0,0.5 
LOCATE POINT , AT 0.6,0.8 USING TRAN 1 : x,y 


1.3.2.2 Accepting Points That Map to Overlapping Viewports 


When you do not change the default viewport but do define other trans- 
formations with the SET WINDOW statement, these transformations all 

map onto the entire NDC space. For example, the following transforma- 
tions all share the same viewport. 


Example 


SET WINDOW , TRAN 1 : 0,100,0,100 
SET WINDOW , TRAN 2: -1, 1, -1, 1 
SET WINDOW , TRAN 3 : 50, 200, O, 5 


In this case, VAX BASIC cannot distinguish which transformation to 
use on the basis of the viewport alone; therefore, it refers to a list of 
established transformations and selects the transformation with the 
highest input priority. 


When more than one transformation is defined, VAX BASIC maintains 

a prioritized list of transformations to use to translate POINT and 
MULTIPOINT input when viewports overlap. At the start of program | 
execution, transformation 1 (defining the entire NDC space) is the only 
transformation on the list; therefore, at the start of program execution, 
transformation 1 is also the transformation with the highest input prior- 
ity. Points input at the start of program execution are interpreted with 
transformation 1. 


When a subsequent transformation is set with a SET TRANSFORMATION, 
SET WINDOW, or SET VIEWPORT statement, this new transformation 
automatically becomes the transformation at the top of the list and, 
therefore, acquires a higher input priority than transformation 1. The 
transformation with the highest input priority is also the current trans- 
formation for output unless a SET INPUT PRIORITY statement has been 
executed (see Section 7.3.3). 
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In the following example, the point 50,50 is the initial point and is 
displayed on the screen using transformation 1 because it is the transfor- 
mation specified in the USING TRAN clause. When the user enters each 
point, the coordinates are assigned to the next elements in the arrays 
x—coords and y_coords. Any point entered by the user falls into the de- 
fault viewport. As no other viewports are defined, the default viewport is 
the viewport for both transformation 1 and transformation 2. The trans- 
formation used to interpret these coordinates into world coordinates is the 
transformation with the highest input priority (in this case, transforma- 
tion 2, because this is the transformation most recently set). The actual 
transformation used to interpret the user-supplied points in the following 
example is assigned to which_tran, the integer variable supplied with the 
MAT LOCATE POINTS statement. 


Example 


DECLARE LONG which_tran 

DIM SINGLE x_coords(12) , y_coords (12) 
SET WINDOW , TRAN 1 : 0,100,0,100 
SET WINDOW , TRAN 2 : 0,25,0,25 


MAT LOCATE POINTS , AT 50,50 USING TRAN 1 & 
: x_coords, y_coords, which_tran 


Overlapping viewports occur only when a transformation other than trans- 
formation 1 is defined. When possible, VAX BASIC maps the coordinates 
of an input point to world coordinates using the transformation that is 
defined for the viewport the point falls into. When viewports overlap, 

a point can fall into more than one viewport and VAX BASIC uses the 
transformation with the highest input priority that also contains the point. 
In Figure 7-5, a user-supplied point can fall into the area of intersection 
of both viewports. As both viewports are valid, VAX BASIC selects the 
viewport with the highest input priority to interpret the input. 
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Figure 7-5: Interpreting POINT Input When Viewports 
Overlap 
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When the user supplies a series of points (MULTIPOINT input), VAX 
BASIC identifies the viewports that contain all of the points. If there is no 
conflict and all of the points are contained within one viewport, then that 
transformation is used. However, when all of the points are contained in 
more than one viewport, the transformation with the highest input priority 
is used. In Figure 7-6, the series of points shown is interpreted with the 
transformation defined for Viewport B. 
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Figure 7-6: Interpreting MULTIPOINT Input When Viewport 
Overlap 
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Note that when transformation 1 has been redefined with a viewport othe 
than 0,1,0,1, it is possible for points to be outside any defined viewport. 
When this happens, VAX BASIC signals an error. Similarly, VAX BASIC 
signals an error when no single viewport contains all of a series of points 


The following example defines several overlapping transformations. 

The list of input priorities changes whenever a new transformation is 
defined, when the SET TRANSFORMATION statement is executed, 

or when the SET INPUT PRIORITY statement is executed. At various — 
points in the program POINT input is requested from a user. The actual 
transformation used cannot be determined until the position of the input 
point is indicated. Remember that VAX BASIC uses the priority list only 
when viewports overlap; if no overlapping viewports are defined, the 
viewport that contains the points is automatically used to transform 

the input coordinates into world coordinates. The number of the actual 
transformation VAX BASIC used is assigned to the variable which_tran. 
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Example 


DECLARE LONG which_tran, & 
SINGLE x1,y1,x2,y2,x3,y3,x4,y4 
i+ 
!TRAN 1 has highest priority at start of program execution 
- 
SET WINDOW , TRAN 2 : 0,10,0,10 !TRAN 2 now has highest input priority 
SET WINDOW , TRAN 3 : -1,1,-1,1 !TRAN 3 now has highest input priority 
SET TRANSFORMATION 2 !TRAN 2 now has highest input priority 
'+ 
!'Tran 2 has the highest priority 
!VAX BASIC assigns the transformation it used to interpret the point 
!'x1,y1 to which_tran 
fe 
LOCATE POINT xi,yi , which_tran 
SET VIEWPORT , TRAN 3 : 0.5,1,0.8,1 !TRAN 3 now has highest input priority 
t+ 
!Tran 3 has the highest priority 
!VAX BASIC assigns the transformation it used to interpret the point 
!x2,y2 to which_tran 
!- 
LOCATE POINT x2,y2 , which_tran 
SET WINDOW , TRAN 4 : 0,0.5,0,0.5 !TRAN 4 now has highest input priority 
'+ 
!'Tran 4 has the highest priority 
!VAX BASIC assigns the transformation it used to interpret the point 
!'x3,y3 to which_tran 
!- 
LOCATE POINT x3,y3 , which_tran 
SET TRANSFORMATION 1 !TRAN 1 now has highest input priority 
1+ 
!'Tran 1 has the highest priority 
!VAX BASIC assigns the transformation it used to interpret the point 
!1x4,y4 to which_tran 
t- 
LOCATE POINT x4,y4 , which_tran 


1.3.3 Changing the Input Priority 


The SET INPUT PRIORITY statement allows you to change the order of 
the transformations on the input priority list. You use the greater than 

( >) or less than (< ) sign to reorder the priorities. For instance, in the 
following example, the SET INPUT PRIORITY statement makes 3 the 
transformation with the highest priority for input regardless of the SET 
TRANSFORMATION 4 statement. Note that the SET INPUT PRIORITY 
statement has no effect on the current transformation for displaying 
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output; in this case, transformation 4 remains the current transformation 
for displaying output. 


Example 


DECLARE SINGLE x,y, & 
LONG which_tran 


SET TRANSFORMATION 4 !TRAN 4 now has the highest input priority 

SET INPUT PRIORITY 3 > 4 !TRAN 3 now has a higher input priority than 4 
I+ 

!Point x,y is interpreted with the transformation 


‘assigned to which_tran 
1. 


LOCATE POINT x,y , which_tran 


If the point x,y is contained in the viewports for both transformation 

3 and transformation 4, VAX BASIC uses the transformation with the 
highest input priority—now transformation 3. Without this SET INPUT 
PRIORITY statement, VAX BASIC would transform the point according to 
the definition of transformation 4, assuming that the point was contained 
in that viewport. 


7.3.4 Setting the Initial Point 


You can select an initial point with the LOCATE POINT and MAT 
LOCATE POINT statements, as shown in previous sections. Alternatively, 
you can set the initial point with the SET INITIAL POINT statement. If 
you have more than one transformation defined, you can specify which 
one VAX BASIC should use to display this point by including an optional 
USING TRAN clause. If you do not include a USING TRAN clause, VAX 
BASIC uses the current transformation to display output. 


The following example instructs VAX BASIC to display the world coordi- 
nate point 850,150 using the transformation previously defined as 2 in the 
program. This point is displayed as the initial prompt at the appropriate 
position on the display surface when input is requested. Note that the 
current transformation is 3 when the SET INITIAL POINT statement is 
executed. 
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Example 


SET WINDOW , TRAN 2 : 0,1000,0,500 

SET VIEWPORT , TRAN 2 : 0.0,0.75,0.0,0.5 
SET WINDOW , TRAN 3 : -100,100,-100,100 
SET VIEWPORT , TRAN 3 : 0.5,1,0.0,0.5 
SET INITIAL POINT, USING TRAN 2 : 850,150 


LOCATE POINT x_user,y_user 


3-5 Setting an Initial Series of Points 


The MAT LOCATE POINTS and MAT GET POINTS statements allow 
you to present the user with one initial point specified in the optional AT 
clause; the SET INITIAL MULTIPOINT statement allows you to present 
a user with a series of points. You supply initial MULTIPOINT data as 
two arrays of world coordinates: an array of x-coordinates and an array 
of y-coordinates. If you have more than one transformation defined, you 
can specify in the optional USING TRAN clause which transformation 
VAX BASIC should use to interpret these initial points. If you do not 
supply an alternative transformation, VAX BASIC uses the current output 
transformation to display the initial points on the screen. 


An optional COUNT clause can be specified with this statement to indicate 
the number of elements from each array to be used for the display. In 
the following example, two arrays of coordinates are declared with 10 
elements each. However, the SET INITIAL MULTIPOINT statement uses 
a COUNT clause to limit the initial MULTIPOINT data to the first seven 
elements of each array (elements 0 through 6). Without the COUNT 
clause, all points in the arrays would be displayed. The output shows 
how this initial set of points is displayed on a VT240. (On some devices, 
the DELETE key can be used to delete the initial series of points.) 
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Example 


DECLARE LONG counter, how_many 
DIM SINGLE x_stars(9),y_stars(9), & 
user_x(40), user_y(40) 
DATA 10,50, 30,60, 45,47.5, 50,29, 45,14, & 
62.5,14, 70,30, 80,19, 82,22, 89,25 
READ x_stars(counter) ,y_stars(counter) FOR counter = 0% TO 9% 


SET WINDOW , TRAN 1 : 0,100,0,100 
t+ 
!Display only seven of the points 
{- 
SET INITIAL MULTIPOINT, COUNT 7 & 
> x stars,y_stars 
MAT LOCATE POINTS , COUNT how_many : user_x, user_y 


Output 
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Note that no USING TRAN clause is included in this statement; therefor 
VAX BASIC transforms the seven points using the current transformatior 
The user can select this initial diagram or move the prompt to select oth: 
points. In this case, the user can supply up to 41 points. 
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3.6 Accepting Points Within Pictures 


When points are accepted during the execution of a picture, the points 
accepted by the LOCATE POINT and MAT LOCATE POINTS statements 
are not affected by the picture transformations specified on the DRAW 
statement that invoked the picture. If you want the input points to be 
affected by these transformations, you should use the GET POINT and 
MAT GET POINTS statements. The coordinates accepted by a GET 
POINT or a MAT GET POINTS statement are transformed according 

to the inverse of the transformations specified on a DRAW statement; 
that is, the device coordinates of input points are transformed to world 
coordinates and then transformed according to the applied transformation 
functions. For instance, if a picture is invoked with SCALE(2) and points 
are input during picture execution, the input points will be transformed 
to world coordinates according to the current transformation, and then 
divided by two (the inverse of SCALE(2)). 


The following example uses the GET POINT and LOCATE POINT state- 
ments in a picture definition. The first screen shows the picture drawn 
without any transformation functions. For the second screen, the picture 
is drawn with the SHIFT function. Notice that the coordinates of the point 
accepted with the LOCATE POINT statement are not shifted. 


Example 


PROGRAM get_the_point 

OPTION TYPE = EXPLICIT 

EXTERNAL PICTURE loc_get_point 
Screen_1: 

DRAW loc_get_point 

SLEEP 5% 

CLEAR 
Screen_2: 

DRAW loc_get_point WITH SHIFT(0.3,0) 
END PROGRAM 
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PICTURE loc_get_point 
OPTION TYPE = EXPLICIT 
DECLARE SINGLE x_coord,y_coord,1x_coord,ly_coord 
PLOT LINES 0.1,0.2; 0.4,0.3; & 
0.3,0.6; 0.1,0.2 
GET POINT x_coord, y_coord 
PLOT POINTS x_coord, y_coord 
LOCATE POINT lx coord, ly_coord 
PLOT POINTS lx_coord, ly.coord 
END PICTURE 


Output Screen 1: 


Z2K-4939-86 
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Output Screen 2: 





™ 
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Similarly, when MULTIPOINT input is accepted within a picture defini- 
tion, the points accepted by the MAT LOCATE POINTS statement are 
not affected by the transformation functions specified on the DRAW state- 
ment that invoked the picture, while points accepted by the MAT GET 
POINTS statement are affected. The device coordinates of input points 
are transformed to world coordinates and then transformed according to 
the applied transformation functions. The following examples illustrate 
the difference between the MAT GET POINTS statement and the MAT 
LOCATE POINTS statement used within a picture. The first picture ac- 
cepts user input with the MAT LOCATE POINTS statement while the 
second picture uses the MAT GET POINTS statement. For purposes of 
illustration, the examples assume the user input is the same for both 
pictures. 
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Example 


PICTURE locate_doodle 
DECLARE LONG CONSTANT max_pts = 26 
DECLARE SINGLE x_array(1 TO max_pts),y_array(i TO max_pts) 
, LONG how_many 
MAT LOCATE POINTS 
, AT 0,0 
, COUNT how_many 
: X array, y_array 
IF how_many > max_pts 
THEN how_many = max_pts 
END IF 
MAT GRAPH LINES , COUNT how_many : x_array,y_array 
END PICTURE 


PICTURE get_doodle 
DECLARE LONG CONSTANT max_pts = 26 
DECLARE SINGLE x_array(1 TO max_pts) ,y_array(1 TO max_pts) 
,» LONG how_many 
MAT GET POINTS 
, AT 0,0 
, COUNT how_many 
: Xarray, y array 
IF how_many > max_pts 
THEN how_many = max_pts 
END IF 
MAT GRAPH LINES , COUNT how_many : x_array,y_array 
END PICTURE 
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& & & 


& & & 


User Input: 
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When the pictures are invoked, only the points retrieved by the MAT GET 
POINTS statement are affected by the transformation functions in the 
DRAW statement. Compare the output of the DRAW statements in the 
following example. 
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Example 


PROGRAM compare 

OPTION TYPE = EXPLICIT 

OPTION ANGLE = DEGREES 

EXTERNAL PICTURE locate_doodle,get_doodle 

t+ 

{Set up point of origin at center for rotation 

1- 

SET WINDOW -50,50,-50,50 

DRAW locate_doodle WITH ROTATE(90) Set up screen 1 

SLEEP 5% 

CLEAR 

DRAW get_doodle WITH ROTATE(90) !Set up screen 2 
END PROGRAM 


Output Screen 1: 
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Output Screen 2: 
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1.4 STRING Input 


Input statements for STRING allow you to: 


e Set up an initial string for the user 
¢ Accept the user-supplied string 


1.4.1 Accepting STRING Input 
You accept STRING input with the LOCATE STRING statement. 


Execution of the LOCATE STRING statement assigns the user-supplied 
string to a string variable you supply. For example: 


DECLARE STRING user_supplied_string 


LOCATE STRING user_supplied_string 
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The LOCATE STRING statement has an optional INITIAL clause. You 
can use this clause to present an initial string to the user. Depending 

on the device, the cursor is placed at the end of the initial string, and 

the user can either press the RETURN key to accept the initial string or 
enter another string. The user-supplied string is concatenated to the initial 
string. However, depending on the device, the user may be able to delete 
the initial string by pressing the DELETE key or CTRL/U. You can detect 
the absence of the initial string in your program. 


You can use various string handling functions to examine the user- 
supplied string. Depending on the the contents of the examined string, 
your program can branch accordingly. In this example, the user has 
responded with the string “sweet”. After execution of the LOCATE 
STRING statement, taste_choice contains the string “Savory?sweet”. 


Example 


DECLARE STRING taste_choice 
LOCATE STRING, INITIAL "Savory?" : taste_choice 


Output 








\ | Savory? sweet | } 
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You can use the null string to indicate a default response, as shown in the 
following example. The following example sets the initial string to “Save 
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drawing [yes]?” informing the user that pressing the RETURN key will 
be interpreted as a positive response. In your program, you can branch 
to different routines according to the user-supplied string. This example 
presents the initial string as a prompt; unless the user has deleted all or 
part of the initial string, the resulting string contains both the prompt and 
the user-supplied response. 


EXTERNAL PICTURE save_it ,menu 

DECLARE STRING CONSTANT initial_prompt = "Save drawing [yes]? " 
DECLARE STRING initial_prompt, whole_string 

LOCATE STRING , INITIAL initial_prompt : whole_string 

V+ 


!'Check if user responded with a <CR> 
t- 
IF whole_string = initial_prompt 
THEN DRAW save_it 
ELSE DRAW menu 
END IF 


4.2 Setting the Initial String 


You can set the initial string with the SET INITIAL STRING statement 
as an alternative to using the INITIAL clause with the LOCATE STRING 
statement. The following statement sets the initial string to “Sooner or 
later [sooner]?”. This informs the user how a default response will be 
interpreted. 


SET INITIAL STRING "Sooner or later [sooner]? " 


Subsequent requests for STRING input use the initial string specified in 
the most recent SET INITIAL STRING statement unless this is overridden 
by an INITIAL clause in a LOCATE STRING statement. 


Note that unless you set an initial string in your program with a SET 
INITIAL STRING statement or with an INITIAL clause on the LOCATE 
STRING statement, no string is presented to the user. 
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7.5 VALUE Input 


Input statements for VALUE allow you to: 


e Set up an initial range of acceptable values 
e Set up an initial value for the user 
¢ Accept the user’s actual input 


7.5.1 Accepting VALUE Input 


You accept VALUE input with the LOCATE VALUE statement. With this 
statement you can optionally declare an acceptable range of values and 
indicate an initial selection. When you do not specify an initial value and 
range, a default range of 0 through 1 and an initial value of 0.5 are used. 
The following example changes the value prompt displayed to the user 
with a LOCATE VALUE statement. 


Example 


DECLARE SINGLE real_value 

LOCATE VALUE , RANGE 5 TO 10 & 
,» INITIAL 8.5 & 
: real_value 


7.5.2 Setting the Initial Value 


The SET INITIAL VALUE statement allows you to set the range of accept 
able values and select an initial value to be presented to the user. You 
can use this statement as an alternative to using the INITIAL clause on 
the LOCATE VALUE statement. The initial default range of 0 through 

1 is used when you do not specify an alternative range. The acceptable 
range is displayed as the prompt to the user; the form of the display varie 
with each device. On a VT240, the display is presented in the form of a 
continuous line with the lowest acceptable value at the bottom and the 
highest acceptable value at the top. This range and initial value are also 
used for any subsequent requests for VALUE input. For example, the 
following SET INITIAL VALUE statement declares that acceptable values 
are within the range 50 through 100 and sets the initial value to 75. 
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Example 


DECLARE SINGLE CONSTANT first = 50, & 
last = 100 
DECLARE SINGLE how_much 


SET INITIAL VALUE, RANGE first TO last : 75 


LOCATE VALUE how_much 


Output 


100,900 





59.900 


2K-5231-86 


An initial value specified in a LOCATE VALUE statement overrides the 
initial value set in the SET INITIAL VALUE statement. However, if no 
INITIAL clause is included in a LOCATE VALUE statement, subsequent 
requests for VALUE input use the last initial value set with a SET INITIAL 
VALUE statement. 


The initial value must lie within the current range. When this is not the 
case, VAX BASIC signals the run-time error ILLINIVAL, “illegal initial 
value” (ERR = 284). 
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7.6 Changing Echo Areas 


The echo area is the portion of your screen where the prompt appears 
and where input can be accepted from a user. It can be all or part of the 
screen. So far in this chapter, the default echo area has been displayed. 
The default boundaries of the echo area for each type of input are device 
dependent. 


You can change the echo boundaries in your application to a preferred 
area of your screen for the CHOICE, STRING, and VALUE echo areas. 


Use the SET ... ECHO AREA statements to change the default echo are: 
You must specify the boundaries of an echo area in device coordinates 
in the order left, right, bottom, top. Because the echo boundaries must 
be in device coordinates, VAX BASIC supplies statements that allow you 
to retrieve the current echo area boundaries. You can retrieve the device 
coordinates of a particular device with the ASK DEVICE SIZE statement. 
This statement is discussed in Chapter 8. To retrieve the boundaries 

of the current echo area on a particular device, use the appropriate 

ASK ... ECHO AREA statement. Boundaries for VAXstations and VT125 
and VT240 terminals are listed in Appendix B. 


The following example retrieves the data for the default VALUE echo arez 
on a VT125, then uses this data to reduce the echo area. You can alter 
the default echo area for STRING and CHOICE input in a similar fashion 
Further examples are given in the reference section of this manual. 
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DECLARE SINGLE xmin,xmax,ymin,ymax, user_val 
ASK VALUE ECHO AREA xmin,xmax, ymin, ymax 

SET VALUE ECHO AREA xmin,xmax, ymin, ymax/2 
LOCATE VALUE user_val 


Output 


1.900 


\ 0.09090 
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27 Summary 


An interactive graphics program can: 


e Set initial input data, such as the options in a menu 

e Accept input from a user, such as the world coordinates of points 
¢ Define the input priority when viewports overlap 

e Change defaults, such as the echo area 


The following chapter shows how to use the input statements discussed 
here when you use more than one device. 
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Chapter 8 


Advanced Graphics Programming 
Techniques 


A complex graphics application can open several different devices for 
simultaneous input and output, store graphics data in files, and display 
the stored data. This chapter shows you how to: 


e¢ Use alternate or multiple devices 

¢ Send graphics output to a data file rather than an output device 
e Display the contents of graphics data files 

¢ Determine the capabilities of various supported devices 

e Define device transformations 


}.1 Using Alternate or Multiple Devices 


To use more than one device, you must include the OPEN ... FOR 
GRAPHICS statement in your program. For example, the following 
statement opens a device and identifies it as device #2. The quoted string 
must be a system name or logical name for an actual device. (The quoted 
string can also be a file name, as discussed in Section 8.2.) 


OPEN "VTA247:" FOR GRAPHICS AS DEVICE #2 


Normally on VAX/VMS systems, all terminals other than your own are 
protected from you. In order to open a terminal other than your own, you 
must have SYSPRV privileges; without these privileges, you can access 
another terminal only if a privileged user issues the DCL command SET 
PROTECTION/DEVICE for that terminal. This command can be included 
in the installation startup file to make such a terminal permanently 
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available to you. If you require changes to your privilege status, see your 
system manager. 


The OPEN ... FOR GRAPHICS statement is optional. If you do not 
explicitly open a device, VAX BASIC opens the default device for you. Th 
default device is opened with the equivalent of the following statement: 


OPEN *" FOR GRAPHICS AS DEVICE #0 


When you do not identify a device with an OPEN ... FOR GRAPHICS 
statement, VAX BASIC automatically uses the default identification of 0, 
which is equivalent to both SYS$INPUT and SYS$OUTPUT. The default 
identification is adequate when you are using only one device, such as 
when you both create a program and display the image on a single video 
display unit; however, you need device identification numbers when you 
use more than one device in an application. 


Note that multiple workstation windows on a VAXstation should be 
identified as separate devices; otherwise, all output is displayed in the 
same window. 


8.1.1 The Device identification Clause 


The device identification number is an integer that you assign to dis- 
tinguish between different devices in your program. The number is 
explicitly assigned to a device in the device identification clause in the 
OPEN ... FOR GRAPHICS statement.! 


Many VAX BASIC graphics statements allow you to optionally specify 
this number for each device. Statements with an optional identification 
clause include the control statements, many input statements, many ASK 
statements, and the statements for device transformations. 


When you do not specify the identification clause, the statement affects 
only the default device (device #0). When you do specify this identifica- 
tion clause, each statement’s effect is limited only to the device identified 
any other devices identified in the application are not affected. For exam- 
ple, the following SET statement changes the VALUE echo area only on 
device #1. 


1 Device identification numbers in OPEN ... FOR GRAPHICS statements are not related to the channel 
numbers specified in OPEN statements. Channel numbers and device identification numbers are 
independent of each other. 
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OPEN "TV38" FOR GRAPHICS AS DEVICE #1 


SET VALUE ECHO AREA #1 : devx_min,devx_max,devy_min,devy_max 


You can specify #0 in statements that include the optional device iden- 
tification clause. However, you can include other devices in statements 
only if the device has already been explicitly opened and identified. 
When a statement specifies a device that has not been identified in an 
OPEN ... FOR GRAPHICS statement, VAX BASIC signals an error. 
Remember that when you do not identify a device, VAX BASIC uses the 
default identification of 0. 


The optional identification clause allows you to specify which device VAX 
BASIC should request and accept input from. The following example sets 
up a different menu for two devices: 


Example 


OPTION TYPE = EXPLICIT 

DECLARE LONG work_choice, fun_choice 

OPEN “office_term" FOR GRAPHICS AS DEVICE #1 

OPEN “home_term" FOR GRAPHICS AS DEVICE #2 

t+ 

!Set initial choice lists for each terminal with 

!'the device identification clause as first optional clause 


t- 

SET INITIAL CHOICE #1 , LIST ("Program" & 
» "Write" & 
» "Review" & 
» "Edit" & 
»"Quit") : 5 

SET INITIAL CHOICE #2 , LIST ("Play more" & 

»"Quit") : 1 
t+ 


!Request input from device #1 
t- 

LOCATE CHOICE #1 : work_choice 
I+ 

!Request input from device #2 


. 


LOCATE CHOICE #2 : fun_choice 


When several optional clauses are included in a statement, the optional 
device identification clause must be the first clause listed in the statement. 
The following statement includes a device identification clause followed 
by an optional COUNT clause. The statement accepts points from a user 
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at the device identified as #2 and stores the number of points entered in 
the variable How_many. 


MAT GET POINTS #2 , COUNT How_many : x_coords, y_coords 


For syntax details of particular statements, see the reference section of thi 
manual. 


8.1.2 Supported Device Types 


Each hardware device supported by VAX GKS has an assigned number 
that indicates the type of device you are using and whether the device is 
to be used for input, output, or both. Device types that are supported by 
VAX GKS are listed with the OPEN ... FOR GRAPHICS statement in th 
reference section. 


When you use the OPEN ... FOR GRAPHICS statement, you can 
optionally specify a device type. For example, the following statement 
opens “RT30”, a system name for a color VT240, device type 13: 


OPEN "RT30" FOR GRAPHICS AS DEVICE #2 , TYPE 13 


When you do not specify a device type, VAX BASIC searches for an 
assignment to the logical name GKS$WSTYPE. If you have made no 
assignment, VAX BASIC searches for a system assignment. If the 
search fails, VAX BASIC uses the default device type of 14, which is a 
monochrome VT240. To find out if a system-wide assignment has been 
made, issue the following DCL command: 


$ SHOW LOGICAL GKS$WSTYPE 


If no translation is available for GKS$WSTYPE, or if you need to overrid 
the system assignment, you can assign the device type for your own 
device to GKS$WSTYPE in your startup procedures. For instance, in 
the login command procedure for a graphics session on a VT240 color 
terminal, include the following DCL command: 


$ ASSIGN 13 GKS$WSTYPE 


If you have already assigned your current device type with this comman 
and do not specify another device type in your program, then VAX BASI' 
uses this assigned value by default and output is displayed, in this case, ; 
the format for a VT240 color monitor. 
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You can have multiple devices of the default device type or any assigned 
device type. You should specify the device type in each OPEN ... FOR 
GRAPHICS statement only if you cannot assign a device type number 
to GKS$WSTYPE, or when you use more than one device type. When 
you specify a device type, your program is no longer portable to another 
device. 


The system name for the device must refer to an actual device of the type 
you specify. In the following example, the device RT247: is opened as 
device type 13, a VT240 with the color option. The system name RT247: 
refers to an actual device that is a color VT240. 


OPEN "RT247:" FOR GRAPHICS AS DEVICE #2 , TYPE 13 


Note that your system configuration may require an alternative method 
of specifying devices such as printers. For instance, to specify a queued 
printer on a VAXcluster, you may have to include the name of the node in 
the quoted string. 


You cannot open a device with an incorrect device type. For instance, you 
cannot open a video display unit as a printer. The following statement 
opens an LA34 printer, device type 31, with a device identification of 1. 
The quoted string my_printer must be translated to the actual LA34 you 
are opening. 


OPEN "my_printer" FOR GRAPHICS AS DEVICE #1, TYPE 31 


Output is displayed on all active devices during program execution. The 
following example opens a VT240 and an LA50O; the picture ellipse is 
displayed on the VT240 screen and printed on the LA50. 


Example 


OPTION TYPE = EXPLICIT 

EXTERNAL PICTURE ellipse 

OPEN "my_printer" FOR GRAPHICS AS DEVICE #1, TYPE 32 
OPEN "VTA83" FOR GRAPHICS AS DEVICE #2, TYPE 13 


DRAW ellipse 


-1.3 Controlling Devices 
Because output is displayed on all active output devices, VAX BASIC 


provides the capability to explicitly inhibit the display of output on spec- 
ified devices. For instance, you could open three devices for interactive 
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graphics, yet want the output displayed on only two of them. To inhibit 
a display on a device, use the DEACTIVATE DEVICE statement; to acti- 
vate the device again, use the ACTIVATE DEVICE statement. The devic: 
identification number is required with each of these statements. 


When VAX BASIC opens a device with the OPEN ... FOR GRAPHICS 
statement, the device is also automatically activated. When no devices 
are explicitly opened and graphics statements are executed, the default 
device is automatically opened and activated. After all devices are opene 
and identified, you can inhibit the display going to one device with the 
DEACTIVATE DEVICE statement. For example: 


DEACTIVATE DEVICE #5 


When you want to display an image on this device later, use the 
ACTIVATE DEVICE statement. 


ACTIVATE DEVICE #5 


You can explicitly deactivate the default device (#0); however, if no 
devices are active and a graphics output statement is executed, VAX 
BASIC reactivates the default device. 


The CLEAR statement allows you to clear the display on a particular 
device. VAX BASIC clears a device automatically when it is first opened. 
When no device identification is included in the CLEAR statement, only 
the display on the default device is cleared. 


The following example uses these three statements to control the display 
of pictures when several devices are active. Logical names are used to 
represent the actual terminals. 


OPTION TYPE = EXPLICIT 
EXTERNAL PICTURE chocolate_candy, salad, balanced_meal 


OPEN "cafe_term" FOR GRAPHICS AS DEVICE #1, TYPE 13 
OPEN "Marys_term" FOR GRAPHICS AS DEVICE #2, TYPE 12 
OPEN "Evs_term" FOR GRAPHICS AS DEVICE #3, TYPE 12 
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DEACTIVATE DEVICE #3 
DRAW chocolate_candy 
ACTIVATE DEVICE #3 
DEACTIVATE DEVICE #2 
DRAW salad 

ACTIVATE DEVICE #2 
CLEAR #1 

CLEAR #2 

CLEAR #3 

DRAW balanced_meal 
SLEEP 10% 

END 


Chocolate_candy is not displayed on the device Evs_term, and salad is not 
displayed on Marys_term, while balanced_meal is displayed on all three 
devices. 


The RESTORE GRAPHICS statement allows you to restore all the graphics 
defaults and attributes to the values at the start of program execution. This 
statement does not accept a device identification; when you use RESTORE 
GRAPHICS, all open devices are closed and all graphics attributes and 
defaults are restored to the initial state at the start of program execution. 


You can explicitly close a device with the CLOSE DEVICE statement. 
This statement is optional; when a program is terminated, VAX BASIC 
automatically closes all open devices. However, it is good programming 
practice to explicitly close any devices that you explicitly open with an 
OPEN ... FOR GRAPHICS statement. You can also use the CLOSE 
DEVICE statement as a safeguard in error handlers, as shown in the 
following example. This program displays the picture circle on devices #1 
and #2. If an error is encountered while device #2 is being opened, 
device #1 is closed and circle is displayed on the default device. 


Example 
PROGRAM open_up 


OPTION TYPE = EXPLICIT 
EXTERNAL PICTURE circle 
DECLARE LONG times 


OPEN "RTA1" FOR GRAPHICS AS DEVICE #1, TYPE 12 
WHEN ERROR IN 
OPEN "exper_term" FOR GRAPHICS AS DEVICE #2, TYPE 12 
USE 
GRAPH TEXT AT 0.5,0.5: "Problems with experimental terminal" 
CLOSE DEVICE #1 
EXIT HANDLER 
END WHEN 


DRAW circle WITH SHEAR(10 * times) FOR times = 1% TO 5% 
END PROGRAM 
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8.2 


Metafiles 


When a program creates a graphics image, you can store this image in a 
file known as a metafile. Metafiles provide you with a convenient methoc 
of storing and reproducing graphics images. They allow you to recreate 
an image without repeatedly processing the data. Metafiles are especially 
useful for: 


e Recreating complex images that are used frequently 


¢ Recreating images from user-supplied input that could not easily be 
reentered 


8.2.1 Creating Metafiles 


To send an image to a metafile, your application program must open 
a metafile as an alternative device. The following OPEN ... FOR 
GRAPHICS statement opens the file grad_swans.pic as device #1 with 
the device type 2, an output metafile. 


device_type = 2 
OPEN "grad_swans.pic" FOR GRAPHICS AS DEVICE #1, TYPE device_type 


Graphics output statements executed after this OPEN ... FOR 
GRAPHICS statement are now directed to device #1, the metafile 
grad_swans.pic. You cannot open an existing metafile as device type 2; 
VAX BASIC can open only a new file. 


The following example opens two devices: a VAXstation II and a metafile 
The program uses the picture swan defined in Chapter 6. It displays the 
image on device #2 (a VAXstation) and stores the image data in the file 
grad_swans.pic, device #1. If no directory is specified, the metafile is 
created in your current directory. 


Example 


OPTION TYPE = EXPLICIT 
EXTERNAL PICTURE swan 

DECLARE SINGLE grad_matrix(4,4) 
DECLARE LONG counter 


OPEN "grad_swans.pic" FOR GRAPHICS AS DEVICE #1, TYPE 2 
OPEN "VTA72" FOR GRAPHICS AS DEVICE #2 , TYPE 41 
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SET WINDOW , TRAN 1 : 0,100,0,100 
FOR counter = 1% TO 7% 
MAT grad_matrix = SHIFT((counter * counter) + (counter * 30) ,0) & 
* SCALE(1/25 * counter) 
DRAW swan WITH grad_matrix 
NEXT counter 
SET TEXT HEIGHT 3 
GRAPH TEXT AT 5,40 :"Seven Swans A-Graduating" 


CLOSE DEVICE #1 
CLOSE DEVICE #2 
END 


Output 


Er 





The image created by this DRAW statement is now stored in the metafile 
grad_swans.pic and displayed on the VAXstation II. The metafile 
grad_swans.pic can now be displayed on any open output device, as 
described in the following section. 
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8.2.2 Displaying the Contents of a Metafile 


Metafiles contain data records identifying the VAX GKS functions requir 
for an output display. Once a valid VAX GKS metafile has been created 
you can display the contents of the metafile with the GRAPH METAFIL 
statement. The contents of the metafile are displayed on all active devic 
The GRAPH METAFILE statement requires the file specification of a val 
metafile or a logical name. For example: 


GRAPH METAFILE "(HEINES .GRAPHICS] grad_swans. pic" 


Images contained in metafiles are displayed with the window and view- 
port specified when the metafile was created, unless you set alternatives 
before the GRAPH METAFILE statement is executed. To display the 
metafile created by the previous example, you must include the GRAPH 
METAFILE statement in a program. This example opens an output devi 
and displays the metafile. If no output device is explicitly opened for th 
display, VAX BASIC displays the metafile on the default device. 


Example 


OPEN "“office_term" FOR GRAPHICS AS DEVICE #1, TYPE 13 
SET WINDOW , TRAN 1 : 0,100,0,100 

GRAPH METAFILE "(HEINES.GRAPHICS] grad_swans.pic" 

END 


The following program Childs_play stores a user’s drawings in metafiles 
and displays them when requested. The drawings can be saved from 
one session to another. The example assumes that a user knows whethe 
any previous metafiles have been created, and that the user knows the 
names of the drawings. Only the current drawing is held in memory. 
Two devices are used: an output metafile, and the default device type fc 
the user’s terminal. 


Example 
PROGRAM childs_play 
OPTION TYPE = EXPLICIT 


DECLARE LONG to_do,how_many, & 
SINGLE x_array(150), y_array(150) 
EXTERNAL SUB display, & 


save_it(SINGLE DIM (), SINGLE DIM (), LONG) 
OPEN "" FOR GRAPHICS AS DEVICE #1 
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UNTIL 0% 

1+ 

!Main menu 

t- 

SET INITIAL CHOICE , LIST ("Draw a new picture" 
"Save the current picture" 
"View an old picture" 
»"Quit this program") 
ae 


& & BP & 


LOCATE CHOICE #1 : to_do 


SELECT to_do 
CASE = 1 
CLEAR 
MAT LOCATE POINTS , #1 & 


, COUNT how_many & 
: X_array, y_array 
IF how_many > 151 
THEN how_many = 151 


END IF 
CASE = 2 
CALL save_it(x_array(),y_array() , how_many) 
CASE = 3 
CALL display 
CASE = 4 
EXIT PROGRAM 
END SELECT 
NEXT 
END PROGRAM 
SUB display 
OPTION TYPE = EXPLICIT 
DECLARE STRING CONSTANT present = & 


“Which drawing? (<CR> = back to menu) " 
DECLARE STRING meta_file 
SET INITIAL STRING #1 : present 


UNTIL 0% 
WHEN ERROR IN 
LOCATE STRING #1 , INITIAL present : meta_file 
IF meta_file = present 
THEN EXIT SUB 
ELSE 
neta_file = MID$(meta_file, 38, 46) 
GRAPH METAFILE meta_file + ".met" 
SLEEP 15% 
CLEAR 
END IF 
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-05,0.95 : "That drawing does not exist," 
0.85 : "please try another." 


SUB save_it(SINGLE x_array(),y_array () ,how_many) 
OPTION TYPE = EXPLICIT 
DECLARE STRING meta_file 
LOCATE STRING , INITIAL "Give it a name> ": meta_file 
neta_file = MID$(meta_file,17,46) 
t+ 


!Inhibit display from user's terminal 
te 


DEACTIVATE DEVICE #1 

OPEN (meta_file + ".met" FOR GRAPHICS AS DEVICE #2, TYPE 2 
MAT PLOT LINES , COUNT how_many : x_array, y_array 

{+ 


!Reactivate user's terminal 
t 


ACTIVATE DEVICE #1 
1+ 
!Close metafile 


t- 
CLOSE DEVICE #2 
END SUB 


8.3 Determining Device Capabilities 


You may need to retrieve information about a device when your applic: 
tion is being used on an unknown device; for instance, an application m 
use the VAX BASIC default values and have no control over the hardwé 
device on which a user might run the application. To retrieve informati: 
about hardware devices in use, VAX BASIC provides two ASK statemen 


e ASK DEVICE TYPE 
e ASK DEVICE SIZE 


The ASK DEVICE TYPE statement retrieves the device type for a device 
previously specified in an OPEN ... FOR GRAPHICS statement, or a 

device implicitly opened by VAX BASIC. For example, the following AS 
statement retrieves information about the device identified as device #1. 
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ASK DEVICE TYPE #1 : device_type 


Once you know the device type, you can branch to alternative routines 
in your program. The following example requests information about an 
unknown device. The application proceeds depending on the values 
retrieved by the ASK statements. VAX BASIC assigns a value for the 
device type to the variable dev_type in the ASK DEVICE TYPE statement. 


Example 
OPTION TYPE = EXPLICIT 


EXTERNAL PICTURE sine_curve 

EXTERNAL SUB VS_start_up,color_rtn 
DECLARE LONG dev_type 

OPEN “user_term" FOR GRAPHICS AS DEVICE #1 


ASK DEVICE TYPE #1 : dev_type 


SELECT dev_type 
CASE = 41 
CALL VS_start_up 
CASE = 13 
CALL color_rtn 
CASE ELSE 
DRAW sine_curve 
CLOSE DEVICE #1 
END SELECT 


The ASK DEVICE SIZE statement retrieves the size of the available display 
surface of the device in use. For instance, the following ASK statement 
requests the size of device opened as 41, a VAXstation II: 


Example 


DECLARE SINGLE horizontal_size,vertical_size, & 
STRING what_measure 

OPEN "my_term" FOR GRAPHICS AS #1 , TYPE 41 

ASK DEVICE SIZE #1 : horizontal_size, vertical_size, what_measure 


For VAXstations, the value assigned to what_measure is “METERS”. When 
the units of measure are not meters, the string assigned is “OTHER”. The 
measurement of the available display surface in the horizontal direction is 
assigned to horizontal size; the measurement in the vertical direction is as- 
signed to vertical_size. You can use these assigned values to change echo 
area boundaries or device viewport boundaries as shown in Section 8.4. 
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Additional information can be retrieved about specific devices with the 
following statements. Each of these statements can include an optional 
device identification. 


e ASK MAX LINE SIZE 

e ASK MAX POINT SIZE 
e ASK MAX COLOR 

e ASK COLOR MIX 

e =6ASK...ECHO AREA 


These statements each retrieve device-specific information that you may 
not be able to predict before run time. When specified, the device ident 
cation clause must be the first optional clause in the statement. For mo1 
details about each of these statements, see Chapters 3, 4, and 7 as well 
the reference material in Chapter 9. 


Appendix B provides device-specific information, such as device coordi- 
nates, for VAXstations and VT125 and VT240 terminals. 


8.4 Device Transformations 


In addition to the normalization transformations described in Chapter 5 
you can also transform an image from NDC space to your device. This 
is known as a device transformation. Device transformations allow you t 
make use of all the available display space on an output device. Howev 
device transformations are dependent on the size of a particular device, 
unlike normalization transformations, which are device independent. 


To recap, the normalization transformation defines the projection of an 
image in the world window onto a viewport in NDC space. Normalizati 
transformations include: 

¢ Setting world window boundaries with the SET WINDOW statemer 


e Setting world (NDC) viewport boundaries with the SET VIEWPOR] 
statement 


e Establishing the current transformation with the SET TRANSFORM/ 
statement 


e Clipping the graphics image within the viewport boundaries with th 
SET CLIP statement 
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A device transformation defines the projection of a portion of NDC space 
onto a device viewport. Device transformations include: 


¢ Selecting a portion of NDC space as the device window with the SET 
DEVICE WINDOW statement 


e Selecting a portion of the device as a device viewport with the SET 
DEVICE VIEWPORT statement 


Figure 8-1 illustrates the progression of both of these kinds of transforma- 
tions. 


jure 8-1: Normalization and Device Transformations 


NDC Space 


rid Window World Viewport 


Device Window Device Viewport 
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The device window is the portion of NDC space to be projected onto your 
screen. The default device window includes all of NDC space with left, 
right, bottom, and top boundaries of 0,1,0,1 respectively. You can specify 
that only a portion of NDC space is projected onto the screen with the 
SET DEVICE WINDOW statement. You cannot select a window larger 
than the NDC space limits. A complementary ASK DEVICE WINDOW 
statement allows you to retrieve the current device window boundaries. 
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The following example sets the device window to 0.65,0.85,0.3,0.5. 
Figure 8-2 illustrates the device window specified. 


OPEN "VTA72" FOR GRAPHICS AS DEVICE #1, TYPE 12 
SET DEVICE WINDOW #1 : 0.65,0.85,0.3,0.5 


Figure 8-2: The Device Window in NDC Space 


NDC Space 


Device Window 
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The image defined in the device window of NDC space is projected ont 
the device viewport, which is a portion of your screen. The default size 
and shape of the device viewport is device dependent; however, it is 
commonly the largest square area your device can accommodate. 


You can change the boundaries of the device viewport with the SET 
DEVICE VIEWPORT statement. The following example identifies the 
device as #1, retrieves the device coordinates with the ASK DEVICE 
SIZE statement, and uses these coordinates to set a new device viewpor 
Figure 8-3 illustrates the projection of the previous device window onto 
square device viewport. 


8-16 Advanced Graphics Programming Techniques 


igure 8-3: 





NDC Space 


DECLARE SINGLE screen_height , screen_width 

OPEN "VTA101" FOR GRAPHICS AS DEVICE #1 

SET DEVICE WINDOW #1 : 0.65,0.85,0.3,0.5 

ASK DEVICE SIZE screen_width, screen_height 

SET DEVICE VIEWPORT #1 : 0, screen_width/2, & 
0, screen_width/2 


The Device Window Is Projected onto the 
Device Viewport 


Device Viewport 
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The actual boundaries of the device viewport are dependent on the device. 
For instance, VAXstations can have multiple viewing windows, while 

the full display area on VT125 and VT240 screens is rectangular. The 
following example shows how to extend the default device viewport to 
the available display surface of VT125 and VT240 terminals. If you do 
not know the dimensions of the particular output device you are working 
with, use the ASK DEVICE SIZE statement to retrieve the appropriate 
values. You can also use the ASK DEVICE VIEWPORT statement to 
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retrieve the current boundaries of the device viewport. Once you know 
the exact dimensions of your screen, you can change the boundaries of th 
device viewport with the SET DEVICE VIEWPORT statement. 


Example 


OPTION TYPE = EXPLICIT 
DECLARE SINGLE horiz_size, vert_size, & 
STRING what_measure 


OPEN "VTA247" FOR GRAPHICS AS DEVICE #1 

ASK DEVICE SIZE #1, horiz_size, vert_size, what_measure 
!+ 

!Use these values to set the device viewport 


!to the full extent of your screen 
t- 


SET DEVICE VIEWPORT #1 : O, horiz_size, 0, vert_size 


Note that both the default device window and the default device viewpor 
are square in shape. Figure 8-3 illustrates a square device window that 
is projected onto a square device viewport. When the aspect ratio is not 
1:1, VAX BASIC overrides your specifications for a device viewport and 
uses the largest possible device viewport that matches the shape of the 
device window. To ensure that the aspect ratio is 1:1, you should set a 
rectangular device window in direct proportion to a rectangular device 
viewport. 


You cannot alter the clipping status in terms of the output device. If 
a graphics object extends beyond the actual boundaries of the device 
window or viewport you specify, the excess of the image is not displayed 


Note that device transformation information is ignored in metafiles and 
metafile output is displayed using the current device window and view- 
port. 


The following subprogram uses the whole screen as the device viewport. 
You can declare and call this subprogram from a graphics main program, 
as shown here. 
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Example 


SUB Full_screen(LONG trans) 
OPTION TYPE = EXPLICIT 
DECLARE STRING temp 


DECLARE SINGLE aspect_ratio, dcx_max, dcy_max 


SET TRANSFORMATION trans 
SET CLIP "OFF" 


ASK DEVICE SIZE dcx_max, dcy_max 
aspect_ratio = dcy_max/dcx_max 
+ 

!'Same ratio as device 

{- 

SET VIEWPORT 0,1,0,aspect_ratio 
t+ 


!Full screen 
t- 


SET DEVICE VIEWPORT 0,dcx_max,0,dcy_max 


SET DEVICE WINDOW 0,1,0,aspect_ratio 
END SUB 


PROGRAM Demo 
EXTERNAL SUB Full_screen(LONG) 
DECLARE SINGLE counter 


CALL Full_screen(1) 
GRAPH LINES 0,1; 1,1; 1,0; 0,0; 0,1 


GRAPH LINES counter,0.0;counter,1.0 FOR counter = 0 TO 1 STEP 0.5 


END PROGRAM 
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Output 








ae Te 
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Although complex manipulations with device viewports are possible, it is 
preferable to manipulate images in NDC space. Rather than divide the 
device viewport into various portions, it is less cumbersome to build a 
composite or complex display in NDC space using normalization transfor 
mations. Once such a composite display is created in NDC space, all of 
NDC space can be mapped to the default device viewport. It is more 
reliable (and easier) to use normalization transformations rather than 
device transformations to manipulate composite images because normali- 
zation transformations are device independent. 
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8.5 Summary 


This chapter has discussed how to: 
¢ Specify different devices in graphics control and input statements, 
such as CLOSE DEVICE and LOCATE CHOICE 


¢ Use metafiles to store graphics output and display the files with the 
GRAPH METAFILE statement 


e¢ Determine device capabilities with the ASK DEVICE TYPE and ASK 
DEVICE SIZE statements, as well as other statements 


e Define device transformations with the SET DEVICE WINDOW and 
SET DEVICE VIEWPORT statements 
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tEFERENCE SECTION 


Chapter 9 


VAX BASIC Graphics Statements 


This chapter provides reference material on each VAX BASIC graphics 
statement. The descriptions are arranged in alphabetical order and include 
the following sections: 


Overview An overview of what the statement does. 
Format The required syntax for the statement. 


Syntax Rules Any rules governing the use of parameters, separators, or other 
syntax items. 


Remarks Explanatory remarks concerning the effect of the statement on 
program execution and any restrictions governing its use. 


Example One or more examples of the statement in a program. Where 
appropriate, sample output is shown. 


Explanation of Syntax Diagrams 


The following tables explain the conventions used in the syntax diagrams 
in this chapter. The syntax diagrams consist of VAX BASIC keywords, 
mnemonics, and punctuation symbols. 


The following symbols are used in the syntax diagrams. 
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Symbol 
UPPERCASE 


lowercase 


[] 


Meaning 


Uppercase words are VAX BASIC keywords that must be 
coded exactly as shown. 


Lowercase words are elements that must be replaced by 
an appropriate user-supplied value. 


Brackets enclose an optional portion of a format. Brackets 
around vertically stacked items indicate that you can 
select one of the enclosed items. You must include all 
punctuation as it appears in the brackets. 


Braces enclose a mandatory portion of a format. Braces 
around vertically stacked items indicate that you must 
choose one of the enclosed items. You must include all 
punctuation as it appears in the braces. 


An ellipsis indicates that the immediately preceding item 
can be repeated. An ellipsis following a format unit 
enclosed in brackets or braces means that you can repeat 
the entire unit. If repeated items or format units must be 
separated by commas, the ellipsis is preceded by a comma 


Caney: 


The following mnemonics are used in the syntax diagrams: 


Mnemonic 
angle 


array 
cond-exp 


const 
data-type 
def 
dev-id 


dev-type 


exp 
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Meaning 
An angle in radians or degrees 


An array; syntax rules specify whether the bounds or dimen- 
sions can be specified 


Conditional expression; used to indicate that an expression 
can be either logical or relational 


A constant value 
A data type keyword 
Specific to a DEF function 


An identification number for a particular graphics device; 
always preceded by a number sign (#) 


The number associated with the particular type of hardware 
device (see Table 9-1) 


An expression 


Mnemonic 
file-spec 

int 

int-exp 
int-var 
label 

line 
line-num 
matrix 


name 


num 
param-list 
pass-mech 
pic-name 
real 
real-exp 
real-var 
str 

str-exp 
str-var 


target 


tran-term 


unsubs-var 


var 
x-array 
x-coord 
y-array 


y-coord 


Meaning 

A file specification 

An integer 

An expression that represents an integer value 
A variable that contains an integer value 

An alphanumeric statement label 

A statement line; may or may not be numbered 
A statement line number 

A two-dimensional array 


A name or identifier; indicates the declaration of a name or 
the name of a VAX BASIC structure, such as a PICTURE 
subprogram 


A numeric value 

A parameter list, such as for a PICTURE subprogram 
A valid VAX BASIC passing mechanism 

The name of a PICTURE subprogram 

A floating-point value 

A floating-point expression 

A floating-point variable 

A character siring 

An expression that represents a character string 

A variable that contains a character string 


The target point of a branch statement; either a line number 
or a label 


A reserved keyword used for a transformation function 


Unsubscripted variable; used to indicate a simple variable, as 
opposed to an array element 


A variable 

An array of values for x-coordinates 

A value for the x-coordinate of a point 
An array of values for y-coordinates 


A value for the y-coordinate of a point 
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ACTIVATE DEVICE 


ACTIVATE DEVICE 


The ACTIVATE DEVICE statement allows you to activate an output 
device that has been explicitly deactivated. Subsequent graphics output is 
displayed on the specified device. 


Format 
ACTIVATE DEVICE #dev-id 


Syntax Rules 


You must supply the number sign (#) with dev-id. 


Remarks 


1. Dev-id specifies the device that should be activated. Unless you spec- 
ify the default device, the device specified must have been identified 
with an OPEN ... FOR GRAPHICS statement. 


2. A device must be open and activated for graphics output to be dis- 
played on that device. The OPEN ... FOR GRAPHICS statement 
implicitly activates an output device. 


3. After a device has been deactivated, graphics output is not displayed 
on that device until an ACTIVATE DEVICE statement is executed. 


4. If no devices are open and activated when an output statement is 
executed, VAX BASIC implicitly opens and activates the default device 
(device #0). 


5. See also the DEACTIVATE DEVICE statement. 
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ACTIVATE DEVICE 


Example 


EXTERNAL PICTURE Basic_crowd,Basic_party_crowd 
OPEN "VTA247" FOR GRAPHICS AS DEVICE #2 
OPEN "RT1" FOR GRAPHICS AS DEVICE #3 


+ 

{Send output only to device #3 

{ - 

DEACTIVATE DEVICE #2 

DRAW Basic_crowd 

{+ 

!Send output to device #2 and #3 
i] = 

ACTIVATE DEVICE #2 

DRAW Basic_party_crowd 
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ASK AREA COLOR 


ASK AREA COLOR 


The ASK AREA COLOR statement allows you to retrieve the current color 
index for areas. 


Format 


ASK AREA COLOR | int-var 


Syntax Rules 
None. 
Remarks 


1. The range of valid color indices is device dependent. Results are 
unpredictable if you use the value assigned to int-var in a subsequent 
SET AREA COLOR statement and the index is undefined for any 
activated device. 


2. On VT125 and VT240 terminals with the color option, the default 
value assigned to int-var represents one of the following colors: 


Index Color 

0 Blak 
1 Green 

2 Red 

3 Blue 


3. See also the SET AREA COLOR, SET/ASK COLOR MIX, and ASK 
MAX COLOR statements. 
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OPTION TYPE = EXPLICIT 

DECLARE LONG color_var 

ASK AREA COLOR color_var 

SET AREA COLOR color_var + 1 

GRAPH AREA 0.0,0.0; 1.0,1.0; 1.0,0.0 
END 


ASK AREA COLOR 
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ASK AREA STYLE 


ASK AREA STYLE 


The ASK AREA STYLE statement retrieves the value for the current area 
style. 


Format 


ASK AREA STYLE _ str-var 
Syntax Rules 
None. 


Remarks 


1. The value assigned to str-var is one of four possible values: 


e HOLLOW 
e SOLID 

e PATTERN 
e HATCH 


2. The default area style is solid. 


3. If the area style is HATCH or PATTERN, various index styles are 
defined in the area style index. See the SET/ASK AREA STYLE 
INDEX statements. 
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ASK AREA STYLE 


OPTION TYPE = EXPLICIT 
EXTERNAL PICTURE strip 
DECLARE STRING which_style 
ASK AREA STYLE which_style 
DRAW strip 
IF which_style = "SOLID" 

THEN SET AREA STYLE "HOLLOW" 
END IF 
DRAW strip WITH SHIFT(0.4,0) 
END 


PICTURE strip 

DIM SINGLE x_strip(3) ,y_strip(3) 
x_strip(0) 
x_strip(1) 
x_strip(2) 
x_strip(3) 
y_strip(0) 
y_strip(1) 
y_strip(2) 
y_strip(3) 
MAT PLOT AREA x_strip, y_strip 

END PICTURE 


oooooo0o°o 
> ~~) OO tO Pe 


Output 


fo ee 


: 


| Se 
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ASK AREA STYLE INDEX 


ASK AREA STYLE INDEX 


The ASK AREA STYLE INDEX statement retrieves the value for the 
current area style index. The index value specifies one of the various 
hatch or pattern styles. 


Format 


ASK AREA STYLE INDEX _int-var 
Syntax Rules 
None. 
Remarks 


1. The area style index specifies one of the various hatch or pattern 
styles. There is no index value for hollow or solid area styles. 


2. Area index values are device dependent. If you use the value assignec 
to int-var in a subsequent SET AREA STYLE INDEX statement and th: 
index specified is not defined for the device, results are unpredictable 
when an area is subsequently displayed. Appendix B lists possible 
indices for VAXstations and VT125 and VT240 terminals. 


3. Examples of possible indices are shown with the SET AREA STYLE 
INDEX statement and also in Chapter 3 of this manual. 
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ASK AREA STYLE INDEX 


Example 


DECLARE LONG which_ind 
ASK AREA STYLE INDEX which_ind 
IF which_ind > 32% 
THEN SET AREA STYLE INDEX (which_ind - 32%) 
END IF 
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ASK CHOICE ECHO AREA 


ASK CHOICE ECHO AREA 


The ASK CHOICE ECHO AREA statement allows you to retrieve the 
boundaries of the current CHOICE echo area. The boundaries are assigned 
in device coordinates. 


Format 
ASK CHOICE ECHO AREA | *4evid : 
, UNIT int-exp 
real-var1, real-var2, real-var3, real-var4 
Syntax Rules 

1. When specified, dev-id must be the first clause listed and must be 
preceded by the number sign (#). 

2. Real-varl must be preceded by a colon if one or more optional clauses 
are included. 

3. Real-var1, real-var2, real-var3, and real-var4 must be floating-point 
variables to represent the left, right, bottom, and top boundaries 
respectively. 

Remarks 

1. The echo area is the portion of your screen where the prompt appears 
and where input can be supplied by a user. The default boundaries 
are device dependent. 

2. VAX BASIC assigns the boundaries for this area in device coordinates 
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ASK CHOICE ECHO AREA 


3. The optional dev-id identifies the device for which you want informa- 
tion. If no identification clause is included, VAX BASIC uses a default 
identification of #0. If an identification clause is included, the device 
specified must have been opened explicitly, or opened by VAX BASIC 
as the default device. 


4. The optional UNIT clause allows you to specify an alternative means 
of supplying the input. For instance, the selection from a menu can 
be indicated with a mouse, or with the keyboard arrow keys. Each of 
these methods of data entry is a different unit. The default unit value 
for int-exp for each input type is 1; the default is used throughout 
this manual. For information about the units available on a particular 
device, see the hardware documentation for that device, as well as the 
VAX GKS documentation. 


5. See also the SET CHOICE ECHO AREA statement. 


6. Note that you cannot retrieve or change the boundaries of the echo 
area for POINT or MULTIPOINT input. These echo areas coincide 
with the default for the device. 


OPTION TYPE = EXPLICIT 
DECLARE SINGLE xmin,xmax, ymin, ymax, 
new_xmin ,new_xmax ,new_ymin, new_ymax, 
LONG which 
ASK CHOICE ECHO AREA xmin, xmax, ymin, ymax 
I+ 
!Set new echo boundaries 
te 


ee 


new_xmin = 0 

new_xmax = xmax 
new_ymin = ymin 
new_ymax = ymax 


SET CHOICE ECHO AREA new_xmin, new_xmax, new_ymin, new_ymax 
SET INITIAL CHOICE , LIST ("Richer" 
»"Poorer" 
, "Better" 
,"Worse") 


: 3 


& & & & 


LOCATE CHOICE which 
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ASK CLIP 


ASK CLIP 


The ASK CLIP statement allows you to determine whether clipping is 
currently on or off. 


Format 


ASK CLIP _ str-var 
Syntax Rules 
None. 
Remarks 


1. The value assigned to str-var is either “ON” or “OFF”. 
Clipping is enabled at the start of program execution. 


3. When clipping is enabled with the SET CLIP “ON” statement, graphic 
images with world coordinate values exceeding the limits of the worl 
window are not displayed. 


4. When clipping is disabled with the SET CLIP “OFF” statement, image 
with world coordinate values that exceed the limits of the world 
window are displayed, provided that the points are also within the 
device window. 


5. When clipping is enabled, STRING precision clips a text string at the 
world viewport boundary. No text string starts beyond the world 
viewport boundary. 


6. When clipping is enabled, CHAR precision clips each text character 
at the world viewport boundary. No character extends beyond the 
world viewport boundary. Some devices display part of a character 
that spans the world viewport boundary. 
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ASK CLIP 


7. When clipping is enabled, STROKE precision clips text precisely at the 
world viewport boundary. For example, if only half a character falls 
inside the world viewport boundary, only this half is displayed on the 
screen. 


DECLARE STRING clipping 

SET WINDOW , TRAN 2 : 0,1,0,0.5 

SET TEXT HEIGHT 0.03 

ASK CLIP clipping 

t+ 

!Graph text - the top line is beyond the boundaries 
!of the world window for TRAN 2 

!- 

GRAPH TEXT AT 0.2,0.7 : "This is the top line" 
GRAPH TEXT AT 0.2,0.3 : "This is the second line" 
GRAPH TEXT AT 0.2,0.2 : "Clipping is " + clipping 


Output 


(SN 


This is the second line 


Clipping is ON 


ee 
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ASK COLOR MIX 


ASK COLOR MIX 


The ASK COLOR MIX statement retrieves values for the intensities of rec 
green, and blue associated with the current color index. 


Format 


ASK COLOR MIX = /[ #dev-id ], INDEX int-exp: real-var1, real-var2, real-var3 


Syntax Rules 
1. When specified, dev-id must be preceded by the number sign (#). 
2. You specify the color index with int-exp. 
3. Real-varl retrieves the intensity associated with red. 
4. Real-var2 retrieves the intensity associated with green. 
5. Real-var3 retrieves the intensity associated with blue. 
Remarks 


1. The optional dev-id identifies the device for which you want informa- 
tion. If no identification clause is included, VAX BASIC uses a defaul: 
identification of #0. If an identification clause is included, the device 
specified must have been opened explicitly, or opened by VAX BASIC 
as the default device. 


2. Values for the intensities of the colors red, green, and blue are greate: 
than or equal to 0.0 and less than or equal to 1.0. 
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ASK COLOR MIX 


3. The default intensity values for color indices 1, 2, and 3 are as follows: 


Color Red Green Blue 

Index Color Intensity Intensity Intensity 
0 Black oO OO OO 
1 Green 0.0 1.0 0.0 

2 Red 1.0 0.0 0.0 

3 Blue 0.0 0.0 1.0 


4. See the SET COLOR MIX statement for more information. Possible 
values for the intensities are listed in Appendix B. 


5. The number of color indices is device dependent. If you use the 
values retrieved with this statement to set colors on a device that does 
not support the same indices, results are unpredictable. 


DECLARE SINGLE red, green, blue 

OPEN "color_term" FOR GRAPHICS AS DEVICE #1 

+ 

!Ask for the 3 default intensities associated with INDEX 2 
!- 

ASK COLOR MIX #1 
GRAPH TEXT AT 0. 


DEX 2 : red, green, blue 

.8 : "Red intensity = " + STR$(red) 

7 : "Green intensity = " + STR$(green) 
6 : "Blue intensity = " + STR$(blue) 
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ASK DEVICE SIZE 


ASK DEVICE SIZE 


The ASK DEVICE SIZE statement lets you determine the actual size of tk 
available display surface on a particular device. 


Format 


ASK DEVICE SIZE [| #dev-id: ] real-var1, real-var2 [ , str-var ] 
Syntax Rules 


1. The optional dev-id must be preceded by a number sign (#) and 
followed by a colon (:). 


2. The size in the horizontal direction is assigned to real-varl1. 
3. The size in the vertical direction is assigned to real-var2. 
4. The unit of measure used is assigned to the optional sér-var. 


Remarks 


1. The optional dev-id identifies the device for which you want informa 
tion. If no identification clause is included, VAX BASIC uses a defaul 
identification of #0. If an identification clause is included, the device 
specified must have been opened explicitly, or opened by VAX BASIC 
as the default device. 


2. The value assigned to the optional str-var is the unit of measure usec 
to interpret real-varl and real-var2. Str-var can be either “METERS” 
or “OTHER”, indicating that the unit of measure is either meters or 
device coordinates. 


3. See Chapter 8 for more examples. 
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ASK DEVICE SIZE 


OPEN "VT101" FOR GRAPHICS AS DEVICE #1 
DECLARE STRING measure 


DECLARE SINGLE x_dev,y_dev 
ASK DEVICE SIZE #1 : x_dev, y_dev 


1+ 


!Use retrieved coords to set a new echo area 
te 


SET CHOICE ECHO AREA #1 : 0,x_dev,0,y_dev 


END 
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ASK DEVICE TYPE 


The ASK DEVICE TYPE statement retrieves the device type of the speci- 
fied device. 


Format 


ASK DEVICE TYPE [ #dev-id: ] int-var 


Syntax Rules 
2. 
Remarks 
1. 
2. 


When specified, dev-id must be preceded by the number sign (#) and 
followed by a colon (:). 


The value assigned to int-var is a valid supported device type. 


The optional dev-id identifies the device for which you want informa 
tion. If no identification clause is included, VAX BASIC uses a defaul 
identification of #0. If an identification clause is included, the device 
specified must have been opened explicitly, or opened by VAX BASIC 
as the default device. 


Valid device type values are shown in Table 9-1 with the OPEN ... 
FOR GRAPHICS statement in this Chapter. This list is complete up 
to the print date on this manual. For the most up-to-date informatio1 
consult the VAX GKS documentation. 
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ASK DEVICE TYPE 


Example 


OPTION TYPE = EXPLICIT 
DECLARE LONG what_type 
OPEN "RT13" FOR GRAPHICS AS DEVICE #2 
'+ 
'Ask for device type of opened device 
{- 
ASK DEVICE TYPE #2 : what_type 
IF what_type = 41 
THEN CALL wkstation_proc 
END IF 
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ASK DEVICE VIEWPORT 


The ASK DEVICE VIEWPORT statement retrieves the current values for 
the boundaries of the device viewport rectangle. 


Format 


ASK DEVICE VIEWPORT = [ #dev-id: ] real-var1, real-var2, real-var3, real-var4 


Syntax Rules 


Remarks 


When specified, dev-id must be preceded by the number sign (#) and 
followed by a colon (:). 


Real-var1,real-var2, real-var3, and real-var4 must be floating-point 
variables to represent the left, right, bottom, and top boundaries 
respectively. 


The optional dev-id identifies the device for which you want informa- 
tion. If no identification clause is included, VAX BASIC uses a default 
identification of #0. If an identification clause is included, the device 
specified must have been opened explicitly, or opened by VAX BASIC 
as the default device. 


A device viewport is the display area on an output device. 


If no previous SET DEVICE VIEWPORT statement has been exe- 
cuted, the values assigned are the default viewport boundaries. If a 
SET DEVICE VIEWPORT statement has been executed, the assigned 
boundaries are equal to the boundaries last established in that state- 
ment unless VAX BASIC overrides those values. When you do not 
maintain an aspect ratio of 1:1, VAX BASIC overrides the viewport 
values with values that maintain the correct ratio. 
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ASK DEVICE VIEWPORT 


OPTION TYPE = EXPLICIT 

OPEN "VTA247" FOR GRAPHICS AS DEVICE #1 

DECLARE SINGLE left_1,right_1i,bottom,top 

SET WINDOW 0,100,0,100 

SET TEXT HEIGHT 4 

ASK DEVICE VIEWPORT #1 : left_1, right_1, bottom, top 

I+ 

!Draw the boundaries of the default viewport of the device 
t- 

GRAPH LINES 0,0; 100,0; 100,100; 0,100; 0,0 

GRAPH TEXT AT 10,80 : "Left boundary = " + STR$(left_1) 
GRAPH TEXT AT 10,70 : "Right boundary = " + STR$(right_1) 
GRAPH TEXT AT 10,60 : "Bottom boundary = " + STR$(bottom) 
GRAPH TEXT AT 10,50 : "Top boundary = " + STR$(top) 

END 


Output 


Left boundary = 0 





Right boundary = 479 
Bottom boundary = 0 


Top boundory = 479 








oe eee” 


ZK-5516-86 
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ASK DEVICE WINDOW 


ASK DEVICE WINDOW 


The ASK DEVICE WINDOW statement allows you to retrieve the current 
values of the boundaries for the device window. 


Format 


ASK DEVICE WINDOW [| #dev-id: ] real-var1, real-var2, real-var3, real-var4 
Syntax Rules 


1. When specified, dev-id must be preceded by a number sign (#) and 
followed by a colon (:). 


2. Real-var1, real-var2, real-var3, and real-var4 must be floating-point 
variables to represent the left, right, bottom, and top boundaries 
respectively. 


Remarks 


1. The optional dev-id identifies the device for which you want informa- 
tion. If no identification clause is included, VAX BASIC uses a default 
identification of #0. If an identification clause is included, the device 
specified must have been opened explicitly, or opened by VAX BASIC 
as the default device. 


2. A device window is the portion of NDC space you select for display. 


3. The default device window boundaries specify the entire NDC space. 
The boundaries of NDC space are 0,1,0,1 for the left, right, bottom, 
and top boundaries respectively. 


4. The values assigned are equal to the values last established with a SE] 
DEVICE WINDOW statement. If no previous SET DEVICE WINDOW 
statement has been executed, the values assigned are the default 
boundaries of the device window. 
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‘*xample 


ASK DEVICE WINDOW 


OPTION TYPE = EXPLICIT 

DECLARE SINGLE left_1,right_1,bottom,top 
OPEN "RT31" FOR GRAPHICS AS DEVICE #1 
SET WINDOW 0,100,0,100 

SET TEXT HEIGHT 4 


ASK DEVICE WINDOW #1 : left_1, right_1, bottom, top 

GRAPH TEXT AT 10,80 : “Left boundary = " + STR$(left_1) 
GRAPH TEXT AT 10,70 : “Right boundary = " + STR$(right_1) 
GRAPH TEXT AT 10,60 : "Bottom boundary = " + STR$(bottom) 
GRAPH TEXT AT 10,50 : "Top boundary = " + STR$(top) 

END 


Output 


(CS 


Left boundary = 
Right houndary = 1 
Bottom boundary = 0 


Top boundary = 


ee eee 


2K -4969-86 
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ASK LINE COLOR 


ASK LINE COLOR 


The ASK LINE COLOR statement allows you to retrieve the current color 
index for lines. 


Format 
ASK LINE COLOR _int-var 


Syntax Rules 
None. 
Remarks 


1. The range of valid color indices is device dependent. Results are 
unpredictable if you use the value assigned to int-var in a subsequent 
SET LINE COLOR statement and the index is undefined for any 
activated device. 


2. On VT125 and VT240 terminals with the color option, the default 
value assigned to int-var represents one of the following colors: 


Index Color 
0 Black 
1 Green 
2 Red 

3 Blue 


3. See also the SET LINE COLOR, SET/ASK COLOR MIX, and ASK 
MAX COLOR statements. 
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ASK LINE COLOR 
*xample 


OPTION TYPE = EXPLICIT 
DECLARE LONG color_var 

ASK LINE COLOR color_var 

SET LINE COLOR color_var + 2 
SET LINE SIZE 5 

GRAPH LINES 0.0,0.5; 1.0,0.5 
SET LINE COLOR color_var 
GRAPH LINES 0.0,0.2; 1.0,0.2 
END 
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ASK LINE STYLE 


ASK LINE STYLE 


The ASK LINE STYLE statement allows you to determine the current style 
of lines. 


Format 


ASK LINE STYLE _ int-var 
Syntax Rules 
None. 
Remarks 


1. The numeric values retrieved for the line style represent the following 
styles: 


Value Line Style 


1 Solid (default) 
2 Dashed 

3 Dotted 

4 Dashed-dotted 


Line styles greater than 4 are device dependent. 
2. The default line style is 1, solid. 


3. Line styles are device dependent. If you use the value assigned to 
int-var in a subsequent SET LINE STYLE statement and this value is 
not supported by any activated device, results are unpredictable. 


4. For illustrations of the various line styles, see the SET LINE STYLE 
statement. 


9-28 VAX BASIC Graphics Statements 


DECLARE LONG whats_mny_line 

t+ 

!Store the current line style 
!- 

ASK LINE STYLE whats_my_line 
SET LINE STYLE 4 

GRAPH LINES 0.4,0.8; 0.6,0.8 
SET LINE STYLE 3 

GRAPH LINES 0.4,0.7; 0.6,0.7 
SET LINE STYLE 2 

GRAPH LINES 0.4,0.6; 0.6,0.6 
1+ 

!'Regain the stored style value 
{- 

SET LINE STYLE whats_my_line 
GRAPH LINES 0.5,0.5; 0.5,0.0 
END 


ASK LINE STYLE 
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ASK MAX COLOR 


ASK MAX COLOR 


The ASK MAX COLOR statement retrieves the maximum color index 
value for the specified device. 


Format 
ASK MAX COLOR = /[ #dev-id: ] num-var 


Syntax Rules 


When specified, dev-id must be preceded by the number sign (#) and 
followed by a colon (:). 


Remarks 


1. The optional dev-id identifies the device for which you want informa- 
tion. If no identification clause is included, VAX BASIC uses a default 
identification of #0. If an identification clause is included, the device 
specified must have been opened explicitly, or opened by VAX BASIC 
as the default device. 


2. Num-var retrieves the maximum color index. Colors from 0 to num- 
var are defined for the device. This statement is valid only for devices 
with contiguous color indices. 


3. The range of color indices is device dependent. If you use the value 


assigned to num-var in a subsequent SET . .. COLOR statement and 
the index value is undefined for any activated device, results are 
unpredictable. 
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ASK MAX COLOR 


OPTION TYPE = EXPLICIT 
DECLARE LONG highest_color 
ASK MAX COLOR highest_color 
SET TEXT COLOR highest_color 
GRAPH TEXT AT 0,0.8 : & 
"This device supports colors from 0 to " + STR$(highest_color) 
END 
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ASK MAX LINE SIZE 


ASK MAX LINE SIZE 


The ASK MAX LINE SIZE statement retrieves the maximum scale factor 
for the width of lines. 


Format 
ASK MAX LINE SIZE [ #dev-id: ] num-var 


Syntax Rules 


When specified, dev-id must be preceded by the number sign (#) and 
followed by a colon (:). 


Remarks 


1. The optional dev-id identifies the device for which you want informa- 
tion. If no identification clause is included, VAX BASIC uses a default 
identification of #0. If an identification clause is included, the device 
specified must have been opened explicitly, or opened by VAX BASIC 
as the default device. 

2. Num-var retrieves the maximum line width scale factor. 


3. The number of line sizes between 1 and num-var varies with each 
device. . 


4. The default value for the line width scale factor is 1. 


5. You can use the value retrieved in num-var to set the line size with a 
SET LINE SIZE statement. However, if this value is undefined for a 
particular device, results are unpredictable. 
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ASK MAX LINE SIZE 


OPTION TYPE = EXPLICIT 

DECLARE LONG fattest 

OPEN “TT55" FOR GRAPHICS AS DEVICE #1 

ASK MAX LINE SIZE #1 : fattest 

SET TEXT FONT -3, "STRING" 

SET TEXT HEIGHT 0.03 

GRAPH TEXT AT 0.1,0.5 : & 
"Fattest line width is " + STR$(fattest) 

SET LINE SIZE fattest 

GRAPH LINES 0.1,0.4; 0.9,0.4 

END 


Output 


( \ 


Fattest line width is 64 





ee ae 


2K-4956-86 
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ASK MAX POINT SIZE 


The ASK MAX POINT SIZE statement retrieves the maximum scale factor 
for POINT output. 


Format 


ASK MAX POINT SIZE [ #dev-id: ] num-var 


Syntax Rules 


Remarks 


When specified, dev-id must be preceded by a number sign (#) and 
followed by a colon (:). 


Num-var retrieves the largest possible scale factor for point sizes. 


The optional dev-id identifies the device for which you want informa- 
tion. If no identification clause is included, VAX BASIC uses a default 
identification of #0. If an identification clause is included, the device 
specified must have been opened explicitly, or opened by VAX BASIC 
as the default device. 


Scale factors from 1 to num-var are available on the device speci- 
fied. The number of different point sizes within the range is device 
dependent. 


Points in the dot marker style are always drawn in the smallest 
possible size. 


You can use the value retrieved in num-var to set the point size with 
a SET POINT SIZE statement. However, if the value is undefined for 
any activated device, results are unpredictable. 
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ASK MAX POINT SIZE 


DECLARE LONG largest 

ASK MAX POINT SIZE largest 

SET POINT SIZE largest 

GRAPH TEXT AT 0.1,0.9 : "The largest point size is "+ STR$(largest) 
GRAPH POINTS 0.5,0.5 


Output 


The largest point size is l2 


ee ee 


2K-5517-86 
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ASK POINT COLOR 


The ASK POINT COLOR statement allows you to retrieve the current 
color index used to display points. 


Format 
ASK POINT COLOR _int-var 


Syntax Rules 
None. 
Remarks 


1. The range of valid color indices is device dependent. Results are 
unpredictable if you use the value assigned to int-var in a subsequent 
SET POINT COLOR statement and the index is undefined for any 
activated device. 


2. On VT125 and VT240 terminals with the color option, the default 
value assigned to int-var represents one of the following colors: 


Index Color 
0 Black 
1 Green 
2 Red 

3 Blue 


3. See also the SET POINT COLOR, SET/ASK COLOR MIX, and ASK 
MAX COLOR statements. 
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OPTION TYPE = EXPLICIT 

DECLARE LONG color_var 

ASK POINT COLOR color_var 
GRAPH POINTS 0.2,0.6 

SET POINT COLOR (color_var + 1) 
GRAPH POINTS 0.4,0.6 

END 


ASK POINT COLOR 
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ASK POINT STYLE 


ASK POINT STYLE 


The ASK POINT STYLE statement allows you to determine the current 
style of points. 


Format 
ASK POINT STYLE _int-var 


Syntax Rules 
None. 
Remarks 
1. The numeric values retrieved for POINT represent the following 


styles: 


Value Point Style 


1 Dot 

2 Plus sign 

3 Asterisk (default) 
4 Circle 

5 Diagonal cross 


These five styles are illustrated with the SET POINT STYLE statemen 
Values greater than 5 are device dependent. 


2. The default point style is 3, an asterisk. 


3. Point styles are device dependent. If you use the value assigned to 
int-var in a subsequent SET POINT STYLE statement and this value : 
not supported by any activated device, results are unpredictable. 
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EXTERNAL PICTURE big_dipper 
DECLARE LONG whats_the_point 

+ 

!'Store the current point style 
t- 

ASK POINT STYLE whats_the_point 
SET POINT STYLE 4 

DRAW big_dipper 

t+ 


‘Regain the stored style value 
{- 

SET POINT STYLE whats_the_point 
DRAW big_dipper 

END 


ASK POINT STYLE 
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ASK STRING ECHO AREA 


The ASK STRING ECHO AREA statement allows you to retrieve the 
_ boundaries of the current STRING echo area. The boundaries are assigne 
in device coordinates. 


Format 
ASK STRING ECHO AREA | *2evid 
, UNIT int-exp 
real-var1, real-var2, real-var3, real-var4 
Syntax Rules 

1. When specified, dev-id must be the first clause listed and must be 
preceded by the number sign (#). 

2. Real-var1 must be preceded by a colon if one or more optional clause 
are included. 

3. Real-var1, real-var2, real-var3, and real-var4 must be floating-point 
variables to represent the left, right, bottom, and top boundaries 
respectively. 

Remarks 
1. The echo area is the portion of your screen where the prompt appear. 


and where input can be supplied by a user. The default boundaries 
are device dependent. VAX BASIC assigns the boundaries for this are 
in device coordinates. 
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' 


ASK STRING ECHO AREA 


2. The optional dev-id identifies the device for which you want informa- 
tion. If no identification clause is included, VAX BASIC uses a default 
identification of #0. If an identification clause is included, the device 
specified must have been opened explicitly, or opened by VAX BASIC 
as the default device. 


3. The optional UNIT clause allows you to specify an alternative means 
of supplying the input. For instance, the selection from a menu can 
be indicated with a mouse, or with the keyboard arrow keys. Each of 
these methods of data entry is a different unit. The default unit value 
for int-exp for each input type is 1; the default is used throughout 
this manual. For information about the units available on a particular 
device, see the hardware documentation for that device, as well as the 
VAX GKS documentation. 


4. See also the SET STRING ECHO AREA statement. 


OPTION TYPE = EXPLICIT 

DECLARE SINGLE xmin,xmax, ymin, ymax, new_ymax 
DECLARE STRING what 

ASK STRING ECHO AREA xmin, xmax, ymin, ymax 

1+ 

Select larger echo boundary 

{- 

new_ymax = ymax * 2 

SET STRING ECHO AREA xmin, xmax, ymin, new_ymax 
LOCATE STRING what 
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ASK TEXT ANGLE 


The ASK TEXT ANGLE statement allows you to retrieve the current ang 
of text rotation. 


Format 
ASK TEXT ANGLE _real-var 


Syntax Rules 
None. 
Remarks 


1. The default text angle is zero. The angle assigned to real-var is 
in radians or degrees; you can select the unit of measure with the 
OPTION ANGLE statement. 


2. <A positive nonzero value assigned to real-var indicates that subsequen 
displays of text are rotated in a counterclockwise direction; negative 
values indicate that subsequent displays of text are rotated in a 
clockwise direction. 


3. Text is rotated about the starting point indicated in the GRAPH TEXT 
statement. 


4. Angles that are integer multiples of 180° display text horizontally. 
5. Angles that are integer multiples of 90° display text vertically. 


6. For illustrations of various text angle settings, see the SET TEXT 
ANGLE statement. 
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OPTION TYPE = EXPLICIT 

OPTION ANGLE = DEGREES 

DECLARE SINGLE turn 

ASK TEXT ANGLE turn 

SET TEXT ANGLE (turn + 45) 

GRAPH TEXT AT 0.2,0.5 : "Where are we now?" 
SET TEXT ANGLE turn 


ASK TEXT ANGLE 


GRAPH TEXT AT 0.2,0.4 : "Back to where we started." 


END 
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ASK TEXT COLOR 


ASK TEXT COLOR 


The ASK TEXT COLOR statements allow you to retrieve the current colo 
index used to draw text characters. 


Format 
ASK TEXT COLOR _ int-var 


Syntax Rules 
None. 
Remarks 


1. The range of valid color indices is device dependent. Results are 
unpredictable if you use the value assigned to int-var in a subsequent 
SET TEXT COLOR statement and the index is undefined for any 
activated device. 


2. On VT125 and VT240 terminals with the color option, the default 
value assigned to int-var represents one of the following colors: 


Index Color 
0 Black 
1 Green 
2 Red 

3 Blue 


3. See also the SET TEXT COLOR, SET/ASK COLOR MIX, and ASK 
MAX COLOR statements. 
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OPTION TYPE = EXPLICIT 
DECLARE LONG color_var 
ASK TEXT COLOR color_var 
GRAPH TEXT AT 0.0,0.6 : 
SET TEXT COLOR color_var 
GRAPH TEXT AT 0.0,0.4 : 
END 


ASK TEXT COLOR 


"This shows the default color." 


+1 
"This is color index 2." 
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ASK TEXT EXPAND 


ASK TEXT EXPAND 


The ASK TEXT EXPAND statement allows you to retrieve the current rati: 
of character width to height. 


Format 
ASK TEXT EXPAND sreal-var 


Syntax Rules 
None. 
Remarks 


1. The value retrieved is the expansion factor used for current GRAPH 
TEXT statements. This value can be set with the SET TEXT EXPAND 
statement. 


2. The default height-to-width ratio is 1.0, which specifies the expansion 
factor defined in the font design. 


3. For illustrations of various expansion settings, see the SET TEXT 
EXPAND statement. 
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DECLARE SINGLE how_fat 
t+ 

!'Store current setting 
te 

ASK TEXT EXPAND how_fat 
SET TEXT EXPAND 2 
GRAPH TEXT AT 0.1,0.9 : 
t+ 

!'Use stored setting 

!- 

SET TEXT EXPAND how_fat 
END 


"This might be hard to read" 
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ASK TEXT EXTENT 


The ASK TEXT EXTENT statement allows you to retrieve values for the 
boundaries of the text extent box for a given text string. 


Format 
ASK TEXT EXTENT [ #dev-id ] , str-exp AT x-coord, y-coord: x-array, y-array 


Syntax Rules 


1. The optional dev-id must be preceded by the number sign (#). 
2. Str-exp contains the characters to be used for the text extent box. 


3. X-coord and y-coord contain the world coordinates of the starting 
position for the text string. 


4. X-array and y-array must each be a one-dimensional array containing 
at least four integer or real elements. Virtual arrays are not valid. 


Remarks 


1. The optional dev-id identifies the device for which you want informa 
tion. If no identification clause is included, VAX BASIC uses a defaul 
identification of #0. If an identification clause is included, the device 
specified must have been opened explicitly, or opened by VAX BASIC 
as the default device. 


2. The text extent box is an imaginary rectangle that exactly surrounds 
the string expression when both the horizontal and vertical justifica- 
tion aspects are normal. 


3. The boundaries of the text extent box are retrieved in world coor- 
dinates in x-array and y-array. This statement only retrieves the 
boundaries of the text box. To draw the text string, you must use a 
GRAPH TEXT statement, as shown in the example. 
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ASK TEXT EXTENT 


4. Current values for the text height, path, angle, and other text attributes 
are taken into consideration when VAX BASIC calculates the text 
extent box. 


5. See also the ASK TEXT POINT statement. 


OPTION TYPE = EXPLICIT 

DIM SINGLE x_coords(3), y_coords(3) 

OPEN "my_term" FOR GRAPHICS AS DEVICE #1 

SET WINDOW 0,100,0,100 

SET TEXT HEIGHT 4 

ASK TEXT EXTENT #1 & 
» “A perfect fit." AT 5,50 & 
: x_coords, y_coords 

GRAPH TEXT AT 5,50 : "A perfect fit." 

'+ : 

!Set area style to hollow 

‘and draw the text extent box 

I- 

SET AREA STYLE "HOLLOW" 

MAT GRAPH AREA x_coords,y_coords 

END 
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ASK TEXT EXTENT 


Output 


(CN 


A perfect Fit. 


a eee 


2K-5234-86 
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ASK TEXT FONT 


ASK TEXT FONT 


The ASK TEXT FONT statement retrieves the number of the font and the 
value of the text precision. 


Format 


ASK TEXT FONT = int-var [ , str-var ] 


Syntax Rules 


Remarks 


The value assigned to int-var specifies the font number. 


The optional str-var specifies the level of precision with which the 
characters are drawn. 


The default font is number -1, which is displayed with stroke preci- 
sion. 


Hardware fonts are device dependent. Most devices support at least 
one hardware font; some support as many as six. When no hardware 
fonts are available, software fonts are used. Software fonts are device 
independent and provide a graphical representation of the defined 
characters. 


Possible values for the level of precision are: STRING, CHAR, or 
STROKE. STRING provides the lowest precision, while STROKE 
provides the greatest. The precision value affects the representation 
of the text height and how text is clipped. For details and more 
examples, see the SET TEXT FONT, SET TEXT HEIGHT, and SET 
CLIP statements. Hardware fonts can be drawn with either STRING 
or CHAR precision; software fonts can only be drawn with STROKE 
precision. 
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ASK TEXT FONT 





DECLARE LONG this_font, & 
STRING precision 
ASK TEXT FONT this_font, precision 
GRAPH TEXT AT 0.1,0.8 : "This is font number " + STR$(this_font) 


GRAPH TEXT AT 0.1,0.7 : "Precision is " + precision 
END 
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ASK TEXT HEIGHT 


ASK TEXT HEIGHT 


The ASK TEXT HEIGHT statement retrieves the current value of the text 
height in world coordinates. 


Format 
ASK TEXT HEIGHT _rea/-var 


Syntax Rules 
None. 
Remarks 


1. Height refers to the height of the uppercase letters in world coordi- 
nates. 


2. The initial text height is 0.035. Adjustments to the world window 
usually require adjustments to the text height. 


3. For more information, see the SET TEXT HEIGHT statement. 
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ASK TEXT HEIGHT 


OPTION TYPE = EXPLICIT 

DECLARE SINGLE current_height 

{+ 

!Ask for height in default scale 


. 


ASK TEXT HEIGHT current_height 


GRAPH TEXT AT 0.0,0.9 : "Current text height is " + STR$(current_height) 


i+ 

!Change the world coordinate scale 

f- 

SET WINDOW 0,100,0,100 

I+ 

'Set new height scale 

{- 

SET TEXT HEIGHT 5 

GRAPH TEXT AT 0,60 :"Height is now 5/100 of" 
GRAPH TEXT AT 0,40 :"the world window" 
SET TEXT HEIGHT current_height 


GRAPH TEXT AT 0,20 : "You won't be able to read this" 


END 
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ASK TEXT JUSTIFY 


ASK TEXT JUSTIFY 


The ASK TEXT JUSTIFY statement retrieves the current values of the 
horizontal and vertical components of text justification. 


Format 
ASK TEXT JUSTIFY © str-var], str-var2 


Syntax Rules 


1. The value for the horizontal component is assigned to str-var1. 
2. The value for the vertical component is assigned to str-var2. 


Remarks 


1. At the start of program execution, the value for both the horizontal 
and vertical components is “NORMAL”; these are the default values 
until a SET TEXT JUSTIFY statement is executed. 


2. Possible values for the horizontal component in str-varl are the 


following: 
Value Effect on Horizontal Component 
LEFT Corresponds to the left side of the text box passing through the 


text position 


CENTER Corresponds to the text position lying midway between the left 
and right sides of the text box 


RIGHT Corresponds to the right side of the text box passing through 
the text position 


NORMAL ___ Depends on the text path—see below 
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3. Possible values for the vertical component in str-var2 are the follow- 


ing: 


Value 
TOP 
CAP 
HALF 


BASE 
BOTTOM 
NORMAL 


Effect on Vertical Component 
The top of the text box passes through the text position. 
The text position passes through the capline of the whole string. 


The text position passes through the half-line of the whole 
string. 


The text position lies on the baseline of the whole string. 
The bottom of the text box passes through the text. 


See below. 


4. NORMAL can be assigned for both the horizontal and vertical com- 
ponents. NORMAL provides a natural justification for each text path. 
For each of the text paths the horizontal and vertical components are 


as follows: 


Text Path 
RIGHT 
LEFT 

UP 
DOWN 


Normal Horizontal Normal Vertical 
LEFT BASE 

RIGHT BASE 

CENTER BASE 

CENTER TOP 


5. For more information and illustrations of various settings of text 
justification, see the SET TEXT JUSTIFY statement. 


Example 


DECLARE STRING horiz_justify, vert_justify 
ASK TEXT JUSTIFY horiz_justify, vert_justify 
IF horiz_justify = "NORMAL" AND vert_justify = "NORMAL" 


THEN 


SET TEXT JUSTIFY "LEFT" , "BOTTOM" 


END IF 
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ISK TEXT PATH 


The ASK TEXT PATH statement retrieves the current value for the direc- 
tion of the text path. 


ormat 
ASK TEXT PATH - sstr-var 


yntax Rules 
None. 
iemarks 


1. Path refers to the direction in which the text is written relative to the 


text angle. 
2. The value assigned to str-var is one of the following values: 
e RIGHT 
e LEFT 
¢ UP 
¢ DOWN 


3. The default value for str-exp is RIGHT. 


4. For illustrations of various text paths, see the SET TEXT PATH state- 
ment. 
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OPTION TYPE = EXPLICIT 
DECLARE STRING CONSTANT my_way = "LEFT" 
DECLARE STRING which_way 


ASK TEXT PATH which_way 
IF which_way = "RIGHT" 

THEN SET TEXT PATH my_way 
END IF 


SET TEXT PATH which_way 
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\SK TEXT POINT 


The ASK TEXT POINT statement allows you to retrieve the coordinates 
for the concatenation point of a text string. 


ormat 


ASK TEXT POINT [| #dev-id ] , str-exp AT x-coord!, y-coord! : x-coord2, y-coord2 
iyntax Rules 


1. The optional dev-id must be preceded by the number sign (#). 
Str-exp contains the characters to be used for the text extent box. 


3. X-coord1 and y-coord1 contain the world coordinates of the starting 
position for the text string. 


4. The world coordinates of the concatenation point for the supplied text 
string are assigned to x-coord2 and y-coord2. 


iemarks 


1. The concatenation point of a text string is the next appropriate point 
where a subsequent text string can be started. 


2. This statement only retrieves the concatenation point. To draw the 
text string, you need to include a GRAPH TEXT statement. 


3. The optional dev-id identifies the device for which you want informa- 
tion. If no identification clause is included, VAX BASIC uses a default 
identification of #0. If an identification clause is included, the device 
specified must have been opened explicitly, or opened by VAX BASIC 
as the default device. 
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4. Current values for the text height, path, angle, and other text at- 
tributes are taken into consideration when VAX BASIC calculates the 
concatenation point. 


5. See also the ASK TEXT EXTENT statement. For an additional exam- 
ple, see the SET TEXT COLOR statement. 





OPTION TYPE = EXPLICIT 

DECLARE SINGLE concat_x, concat_y 
DIM SINGLE x_coords(3), y_coords(3) 
OPEN "VT21" FOR GRAPHICS AS DEVICE #1 
SET WINDOW 0,100,0,100 

SET TEXT HEIGHT 4 


ASK TEXT EXTENT #1 , & 
"A perfect fit." AT 5,50 & 
: x_coords , y_coords 

ASK TEXT POINT #1 , & 
"A perfect fit." AT 5,50 & 


: concat_x, concat_y 
GRAPH TEXT AT 5,50 : "A perfect fit." 
4 
inet area style to hollow 
'- 
SET AREA STYLE "HOLLOW" 
! 
nee the text box 
ite 
MAT GRAPH AREA x_coords, y_coords 
! 
‘Aaa more text at the concatenation point 
1- 
GRAPH TEXT AT concat_x, concat_y : "Seeing is believing!" 
END 
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Output 


eer rs 


Seeing is belleving? 


ee oe eee ee 


2K-5237-86 
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ASK TEXT SPACE 


The ASK TEXT SPACE statement retrieves the value for the current 
spacing between characters. 


Format 
ASK TEXT SPACE _real-var 


Syntax Rules 
None. 
Remarks 


1. Space refers to the distance between adjacent characters. The distanc 
is expressed as a fraction of the text height. 


2. The default value for the spacing is 0, which produces adjacent 
characters spaced according to the font design. 


3. A positive real-var value inserts more space between characters. 
4. A negative real-var value causes characters to be closer together. 


5. Subsequent GRAPH TEXT statements use the spacing value indicatec 
by real-var until a SET TEXT SPACE statement is executed. 


9-62 VAX BASIC Graphics Statements 


ASK TEXT SPACE 


DECLARE SINGLE spaced_out 
ASK TEXT SPACE spaced_out 
SET TEXT FONT -8, "STROKE" 
SET TEXT HEIGHT 0.04 
GRAPH TEXT AT 0.0 


,0.9 : "This shows the standard text spacing" 
GRAPH TEXT AT 0.0,0.8 
0. 


: "for font -8 with STROKE precision." 


GRAPH TEXT AT 0.0,0.7 : "Space value is " + STR$(spaced_out) 


Output 


! This shows the standard text spacing \ 


for font -8 wtth STROKE preciston. 


Space value 4s 0 


ee ae ee | 


ZK-4880-86 
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ASK TRANSFORMATION 


The ASK TRANSFORMATION statement lets you determine which 
transformation is currently being used to map world coordinate points 
onto the world viewport in NDC space. 


Format 
ASK TRANSFORMATION _ int-var 


Syntax Rules 
The value assigned to int-var is an integer between 1 and 255. 
Remarks 


1. The transformation assigned to int-var is the transformation currently 
used to transform world coordinate points for display onto the world 
viewport in NDC space. 


2. All subsequent graphics output and input use this transfor- 
mation number until a different number is specified in a SET 
TRANSFORMATION, SET VIEWPORT, or SET WINDOW state- 
ment. If none of these statements has been executed, the current 
transformation is 1. 


3. See also the SET INPUT PRIORITY statement. 
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xample 
DECLARE LONG which_tran 


ASK TRANSFORMATION which_tran 
IF which_tran = 1 
THEN SET TRANSFORMATION 2 
ELSE GOTO Set_up_screens 
END IF 
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ASK TRANSFORMATION LIST 


The ASK TRANSFORMATION LIST statement retrieves the list of define 
transformation numbers, starting with the transformation with the highes 
priority for input. 


Format 
ASK TRANSFORMATION LIST /, COUNT int-var: ] int-array 


Syntax Rules 


1. When specified, the COUNT clause must be followed by a colon (:). 


2. Int-array must be a one-dimensional array containing integer or real 
data types. Virtual arrays are invalid. 


Remarks 


1. The values assigned to int-array are transformation numbers for all 
defined transformations. The list is ordered by input priority, starting 
with the transformation with the highest priority. 


2. Int-array can be larger than the actual number of transformations. If 
the number of defined transformations is larger than the size of int- 
array, the actual number of defined transformations can be retrieved i 
int-var with the optional COUNT clause. 


3. For more information about input priorities, see the SET INPUT 
PRIORITY statement. 
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xample 


DECLARE LONG how_many 
DIM LONG xforms(15) 


ASK TRANSFORMATION LIST , COUNT how_many : xforms 
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ASK VALUE ECHO AREA 


The ASK VALUE ECHO AREA statement allows you to retrieve the 
boundaries of the current VALUE echo area. The boundaries are assignec 
in device coordinates. 


Format 
ASK VALUE ECHO AREA | *2evid : 
, UNIT int-exp 
real-var1, real-var2, real-var3, real-var4 
Syntax Rules 

1. When specified, dev-id must be the first clause listed and must be 
preceded by the number sign (#). 

2. Real-varl must be preceded by a colon if one or more optional clause 
are included. 

3. Real-var1, real-var2, real-var3, and real-var4 must be floating-point 
variables to represent the left, right, bottom, and top boundaries 
respectively. 

Remarks 

1. The echo area is the portion of your screen where the prompt appear: 
and where input can be supplied by a user. The default boundaries 
are device dependent. 

2. VAX BASIC assigns the boundaries for this area in device coordinates 
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ASK VALUE ECHO AREA 


The optional dev-id identifies the device for which you want informa- 
tion. If no identification clause is included, VAX BASIC uses a default 
identification of #0. If an identification clause is included, the device 
specified must have been opened explicitly, or opened by VAX BASIC 
as the default device. 


The optional UNIT clause allows you to specify an alternative means 
of supplying the input. For instance, the position of points can be 
entered with a mouse, or with the keyboard arrow keys. Each of these 
methods of data entry is a different unit. The default unit value for 
int-exp for each input type is 1; the default is used throughout this 
manual. For information about the units available on a particular 
device, see the hardware documentation for that device, as well as the 
VAX GKS documentation. 


See also the SET VALUE ECHO AREA statement. 


OPTION TYPE = EXPLICIT 
DECLARE SINGLE xmin,xmax, ymin,ymax, & 


new_xmin ,new_xmax ,new_ymin ,new_ymax, what 


ASK VALUE ECHO AREA xmin, xmax, ymin, ymax 


1+ 


!Select echo boundary on bottom right of screen 


new_xmin = 0 
new_xmax = xmin/2 
new_ymin = ymin 
new_ymax = ymax/2 


SET VALUE ECHO AREA new_xmin, new_xmax, new_ymin, new_ymax 
LOCATE VALUE what 
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ASK VIEWPORT 


The ASK VIEWPORT statement retrieves the current values for the 
boundaries of the world viewport. 


Format 


ASK VIEWPORT /, TRAN int-exp: | real-var!, real-var2, real-var3, real-var4 


Syntax Rules 


Remarks 


When included, the optional TRAN clause must be followed by a 
colon (:). 

Int-exp must be between 1 and 255. 

Real-var1, real-var2, real-var3, and real-var4 must be floating-point 


variables to represent the left, right, bottom, and top boundaries 
respectively. 


If more than one transformation is defined, you can use the optional 
TRAN clause to specify the transformation you want information 
about. If the TRAN clause is not specified, the viewport boundaries 
for the default transformation are assigned. 


If no SET VIEWPORT statement has been executed, the boundary 
values assigned are for the default world viewport. 


The default world viewport is the entire NDC space. The bound- 
aries of NDC space are 0,1,0,1 for the left, right, bottom, and top 
boundaries respectively. 


See also the SET VIEWPORT statement. 
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ASK VIEWPORT 


DECLARE LONG left_1,right_1,bottom,top 


ASK VIEWPORT , TRAN 2 


: left_1,right_1, bottom, top 
1+ 


!'Use TRAN 2 boundaries to set a new viewport for TRAN 4 
t- 


SET VIEWPORT , TRAN 4 : left_1,right_1/2,bottom,top/2 
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ASK WINDOW 


The ASK WINDOW statement retrieves the current values for the bound- 
aries of the world window. 


Format 
ASK WINDOW /, TRAN int-exp: | real-var1, real-var2, real-var3, real-var4 


Syntax Rules 


1. When included, the optional TRAN clause must be followed by a 
colon (:). 


2. Int-exp must be between 1 and 255. 


3. Real-varl, real-var2, real-var3, and real-var4 must be floating-point 
variables to represent the left, right, bottom, and top boundaries 
respectively. 


Remarks 


1. If more than one transformation is defined, you can use the optional 
TRAN clause to specify the window you want information about. 
If the TRAN clause is not specified, the boundaries for the default 
window (TRAN 1) are retrieved. 

2. If no SET WINDOW statement has been executed, the boundary 
values assigned are for the default world window. 


3. The default world window boundaries are 0,1,0,1 for the left, right, 
bottom, and top boundaries respectively. 


4. For more information about the world window, see the SET WINDOV 
statement and Chapter 5 in this manual. 
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OPTION TYPE = EXPLICIT 
EXTERNAL PICTURE sine_curve,fudge_it 
DECLARE LONG left_1,right_1,bottom,top 


ASK WINDOW, TRAN 2 : left_1, right_1, bottom, top 
IF bottom <= -1 AND top >= 1 
THEN 
DRAW sine_curve 
ELSE 
DRAW fudge_it 
END IF 
END 
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CLEAR 


The CLEAR statement clears graphics text and images from the screen. 


Format 
CLEAR [| #dev-id ] 


Syntax Rules 
The optional dev-id must be preceded by a number sign (#). 
Remarks 


1. The optional dev-id identifies the device for which you want informa- 
tion. If no identification clause is included, VAX BASIC uses a default 
identification of #0. If an identification clause is included, the device 
specified must have been opened explicitly, or opened by VAX BASIC 
as the default device. 


2. Output devices are not implicitly cleared before graphics output 
statements are executed. If you do not clear a display, subsequent 
displays are overlaid on any previous output from the program. 


3. Output devices are implicitly cleared when they are opened. 
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CLEAR 


EXTERNAL PICTURE Select_menu, sub_menu 

OPEN "term_name" FOR GRAPHICS AS DEVICE #1 

OPEN “VT231" FOR GRAPHICS AS DEVICE #2 

OPEN “rec_term" FOR GRAPHICS AS DEVICE #3 

{+ 

!Select_menu displayed on all activated devices 

t- 

DRAW Select_menu 

1+ 

!Clear the display on device #1 only 

' oH 

CLEAR #1 

I+ 

!Select-menu display still active on devices #2 and #3 
!Select-menu overlaid with sub-menu on devices #2 and #3 
!Sub-menu displayed by itself on device #1 

! - 

DRAW sub_menu 
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CLOSE DEVICE 


The CLOSE DEVICE statement allows you to explicitly close a specified 
device. Subsequent graphics output will not be displayed on this device. 


Format 
CLOSE DEVICE #dev-id 


Syntax Rules 
You must supply the number sign (#) with dev-id. 
Remarks 


1. When a device is closed, graphics output cannot be displayed on 
that device. However, graphics output is displayed at all other active 
devices. 


2. VAX BASIC implicitly closes all open devices when a graphics pro- 
gram terminates. 


3. VAX BASIC implicitly deactivates the specified device if it is active 
when the CLOSE DEVICE statement is executed. 


4. If the default device is closed and no other device is open, VAX 
BASIC reopens the default device when subsequent graphics output 
statements are executed. 


5. If you intend to open the same device later during program execution, 
it is more efficient to deactivate the device rather than close it. 
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OPTION TYPE = EXPLICIT 

EXTERNAL PICTURE US_political, US_relief 
OPEN "RT47" FOR GRAPHICS AS DEVICE #1 
OPEN "VTA247" FOR GRAPHICS AS DEVICE #2 
OPEN "my_term" FOR GRAPHICS AS DEVICE #3 
t+ 

!Display metafile on all devices 

f- 

GRAPH METAFILE "states_outline.pic" 

i+ 

!Close device #1 

{- 

CLOSE DEVICE #1 

t+ 

!Deactivate, rather than close, device #2 
t- 

DEACTIVATE DEVICE #2 

I+ 

!Draw picture on device #3 only 

{- 

DRAW US_political 

t+ 

!'Reactivate device #2 

ACTIVATE DEVICE #2 

CLEAR #3 

1+ 

!Display picture on devices #2 and #3 

{- 

DRAW US_relief 

END 


CLOSE DEVICE 
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DEACTIVATE DEVICE 


The DEACTIVATE DEVICE statement deactivates the specified output 
device. Subsequent graphics output will not be displayed on this device. 


Format 
DEACTIVATE DEVICE #dev-id 


Syntax Rules 
You must supply the number sign (#) with dev-id. 
Remarks 


This statement deactivates, but does not close, the specified device. 
2. This statement is ignored if the specified output device is not activated. 


3. If the default device (#0) is deactivated and subsequent graphics 
output statements are executed, VAX BASIC displays the output at 
all other active devices. If no other devices are activated, VAX BASIC 
reactivates the default device for output. 


4. See also the ACTIVATE DEVICE statement. 
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OPTION TYPE = EXPLICIT 

EXTERNAL PICTURE Sine_curve, ellipse 

DIM SINGLE x_array(20) ,y_array(20), 
x_curve(12) , y_curve(12) 


OPEN "BASIC_term" FOR GRAPHICS AS DEVICE #1 


DEACTIVATE DEVICE 


OPEN “my_vax" FOR GRAPHICS AS DEVICE #2 , TYPE 41 


t+ 

!Display on all active devices 
I- 

DRAW ellipse 

DEACTIVATE DEVICE #2 

t+ 

!Display on all active devices except #2 
{- 

DRAW sine_curve 

ACTIVATE DEVICE #2 

+ 


!Display on all devices 
{- 


GRAPH TEXT AT 0.5,0.5 :"Display on all open devices" 
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DRAW 


The DRAW statement invokes the specified PICTURE subprogram. 
Optional transformation functions allow you to invoke the picture with 
altered world coordinates. 


Format 


DRAW _pic-name [ (param-list) ] [ WITH tran-term [ * tran-term]...] 


tran-term: 


SCALE (real-exp [, real-exp]) 
SHEAR (angle) 

SHIFT (real-exp, real-exp) 
ROTATE (angle) 
TRANSFORM 

num-matrix 


Syntax Rules 


Pic-name must be a valid VAX BASIC picture name. 


2. Parameters in the param-list must agree in number and data type with 
the parameters in a PICTURE statement. 


3. Tran-term must be one of the VAX BASIC transformation functions 
listed or a valid user-supplied transformation matrix. 


4. The value for angle supplied with the ROTATE and SHIFT functions 
can be in radians or degrees, as specified in the OPTION ANGLE 
statement. 


9-80 VAX BASIC Graphics Statements 


emarks 


DRAW 


When DRAW WITH num-matrix is used, num-matrix must be a two- 


dimensional numeric matrix with lower bounds of zero and upper 


bounds of 4 in both directions. VAX BASIC signals a compile-time 
error when the compiler detects a nonzero-based matrix; otherwise, a 
run-time error is signaled. Num-matrix cannot be a packed decimal or 
a virtual array. 


Pictures displayed with the DRAW statement should be declared with 
the EXTERNAL statement. 


DRAW statements can be included in a picture to invoke another 
picture or to invoke the picture recursively. 


Graphics objects displayed within a picture with PLOT are affected 
by transformation functions included in the DRAW statement that 
invokes the picture; objects displayed with GRAPH are not affected by 
transformation functions. 


When text is drawn in a picture with GRAPH TEXT , the text attributes 
are not automatically adjusted according to the transformation func- 
tions on the DRAW statement that invokes the picture. However, 

the text height and text starting point can be adjusted with the 
TRANSFORM function for SHIFT and positive SCALE transforma- 
tions. For an example on how to do this, see the TRANSFORM 
function in this chapter. 


The order of the transformation functions can affect the results of 
transformations when more than one function is included because 
transformation functions are not associative. VAX BASIC transforms 
points in the order of the transformation functions in the DRAW 
statement; therefore SHIFT(2,1) * SCALE(3) does not result in the 
same coordinate values as SCALE(3) * SHIFT(2,1). 


SCALE 
The SCALE function multiplies the coordinates of point x,y by the 
arguments supplied. SCALE(A,B) changes the coordinates of the point 


to A*x,B*y. SCALE(A) changes the coordinates of a point to A*x,A*y. 
Arguments can be less than 1 to effect a decrease in size. 
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The resulting matrix for SCALE(A,B) is as follows: 


When you supply just one argument with the SCALE function, 
both the x- and y-coordinates of a point are multiplied by the same 
argument. To affect a change in only one dimension, you can supply 
1 as the second argument, for example SCALE(0.5,1), or SCALE(1,2). 


See Example 1. 
7. SHEAR 
The SHEAR function changes the coordinates of point x,y so that the 


resulting point leans forward by the angle specified. The resulting 
point is (x+y * TAN(A)),y. Arguments can be negative. 


The SHEAR function requires an argument in degrees or radians; you 
can select the unit of measure with the OPTION ANGLE statement. 


The resulting matrix for SHEAR(A) is as follows: 


1 
TAN (A) 


0 
A 0 
0 1 
0 0 


ooro 
sm OO°0 


See Example 2. 
8. SHIFT 


The SHIFT function moves the point x,y to the resulting point 
x+A,y+B. Arguments can be negative. 


The resulting matrix for SHIFT(A,B) is as follows: 
1000 
0100 
0010 
ABO1 


See Example 3. 
9. ROTATE 


Like SHEAR, the ROTATE function requires an argument in degrees 
or radians. You select the unit of measure with the OPTION ANGLI 
statement; the default is radians. A positive argument rotates the 
point x,y in a counterclockwise direction about the point of origin 
of the world coordinates. A negative value rotates the point in a 
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11. 


DRAW 


clockwise direction. You can alter the point of origin by setting the 
window such that the point 0,0 is at the center of the window. 


The resulting matrix for ROTATE(A) is as follows: 


COS(A) SIN(A) 0 0 
-SIN(A) COS(A) 0 0 
0 0 10 
0 0 01 


See Example 4. 
TRANSFORM 


The TRANSFORM function returns the cumulative transformations 
for all transformations in current picture invocations. TRANSFORM 
takes no arguments. Note that current transformations are passed to 
pictures by default; therefore, when you invoke a picture with the 
TRANSFORM function on the DRAW statement, the transformations 
in the DRAW statement are applied twice. 


See Example 5. 
Num-matrix 


You can specify your own two-dimensional matrix to substitute for 

a predefined VAX BASIC transformation function. The matrix must 
have lower bounds of zero and upper bounds of 4 in both directions. 
Row and column zero should not be assigned values as VAX BASIC 
uses these elements during matrix manipulation. For instance, rather 
than use a combined transformation such as SHIFT * SHEAR, you can 
assign the combination matrix to your own array: 


MAT my_way = SHIFT(2,1) * SHEAR(25) 


DRAW circle WITH my_way 


Similarly, you can initialize an array with your own choice of values 
and use this with the DRAW statement: 


DRAW circle WITH evs_way 


Note that when a transformation function consists of a numeric array 
that is not a 4 by 4 matrix, a fatal error is signaled. VAX BASIC 
signals a compile-time error when the compiler detects a nonzero 
based matrix; otherwise, a run-time error is signaled. 
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A fatal error is signaled when VAX BASIC cannot compute the invers 
of the num-matrix in a DRAW statement and points in a picture are 
input using the GET or MAT GET statement. See Chapter 7 for 
information about input within picture definitions. 


See Example 6. 


12. Transformation functions in DRAW statements within a picture are 
cumulative. That is, when a second or subsequent picture is invoked 
within a picture definition, the transformations from all of the relevan 
DRAW statements are applied to the points generated by the second c 
subsequent picture. For example, in the following picture, the picture 
nest2 is invoked with a DRAW statement equivalent to DRAW WITH 
SHIFT(50,0) * SCALE(2,1). 


Example 


PICTURE nest i 
EXTERNAL PICTURE nest2 


DRAW nest2 WITH SCALE(2,1) 
END PICTURE 
t+ 


!Invoke picture nesti 
1- 


DRAW nest1 WITH SHIFT(50,0) 


See the TRANSFORM function for more information on accumulated 
transformations. 


Example 1 


EXTERNAL PICTURE box(LONG) 
DRAW box(3) 

DRAW box(1) WITH SCALE(1.5,1.5) 
END 
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PICTURE box(LONG line_style) 
SET LINE STYLE line_style 
PLOT LINES 0.4,0.6; 


& & & & 


ooo°o 
& Poa 
oo0o°o 


. 
. 
° 


QOrrh @ 


END PICTURE 


Output 1 








ZK-4952:86 
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Example 2 


EXTERNAL PICTURE box(LONG) 
DRAW box(3) 

DRAW box(1) WITH SHEAR(0. 25) 
END 


Output 2 


(CN 


ZK-4957-86 
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Example 3 


EXTERNAL PICTURE box(LONG) 
DRAW box(3) 

DRAW box(1) WITH SHIFT(-0.3,0) 
END 


Output 3 


as 


Ie 


ZK-4963-86 
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Example 4 


OPTION ANGLE = RADIANS 
EXTERNAL PICTURE box(LONG) 
DRAW box(3) 

DRAW box(4) WITH ROTATE(0.25) 
DRAW box(1) WITH ROTATE(0.5) 
END 


Output 4 
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PROGRAM demo_transforn 
OPTION ANGLE = RADIANS 
EXTERNAL PICTURE house 
SET WINDOW -1,1,-1,1 
DRAW house 
DRAW house WITH ROTATE(1) 

END PROGRAM 


PICTURE house 
EXTERNAL PICTURE look. 


out 
PLOT LINES : 0; 0 ; & 
6; O 


-8,0.0; 
-2,0.6; & 


0.2,0. 
0.8,0. 
0.2,0.0 

PLOT AREA 0.2,0.6; 0.5,0.8; 0.8,0.6 


DRAW look_out WITH TRANSFORM 
END PICTURE 
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PICTURE look_out 





PLOT LINES : 0.4,0.3; 0.4,0.5; 0.6,0.5; & 
0.6,0.3; 0.4,0.3 

PLOT LINES 0.4,0.4; 0.6,0.4 

PLOT LINES 0.5,0.3; 0.5,0.5 
END PICTURE 
Output 5 

™~., 
N 
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DRAW 


Example 6 


OPTION ANGLE = DEGREES 

EXTERNAL PICTURE box(LONG) 

DECLARE SINGLE prog_matrix(4,4) 

MAT prog_matrix = ROTATE(15) * SCALE(1.5,1) 
DRAW box(3) 

DRAW box(1) WITH prog_matrix 

END 


Output 6 
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END PICTURE 


‘ND PICTURE 


The END PICTURE statement marks the end of a PICTURE subprogram. 


ormat 
END PICTURE 


yntax Rules 


None. 


iemarks 
1. When an END PICTURE statement is executed, execution of the 
picture is terminated. Control is returned to the statement following 
the DRAW statement that invoked the picture. 
2. See also the EXIT PICTURE statement. 
xample 


PICTURE sample 

EXTERNAL PICTURE box(LONG) 

DRAW box(3) 

GRAPH TEXT AT 0.1,0.8 : "One Way Out" 
END PICTURE 
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EXIT PICTURE 


Format 


The EXIT PICTURE statement allows you to terminate execution of a 
PICTURE subprogram. 


EXIT PICTURE 


Syntax Rules 


Remarks 


None. 


1. When an EXIT PICTURE statement is executed, execution of the 
picture is terminated. Control is returned to the statement following 
the DRAW statement that invoked the picture. 


2. See also the END PICTURE statement. 


PROGRAM draw_sample 
EXTERNAL PICTURE sample (LONG) 
DRAW sample(100) 

END PROGRAM 


PICTURE sample(LONG pass) 
IF pass = 100% 
THEN 
GRAPH TEXT AT 0.1,0.7 : "Emergency exit" 
EXIT PICTURE 
END IF 
GRAPH TEXT AT 0.1,0.6 : "Exit ahead" 
END PICTURE 
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GET POINT 


A GET POINT statement accepts a single point of user input. 


Format 


#dev-id 
GET POINT , UNIT int-exp 
, AT x-coord, y-coord [ USING TRAN int-exp] 


x-coord, y-coord [ , int-var] 


Syntax Rules 


1. When specified, dev-id must be the first clause listed and must be 
preceded by the number sign (#). 


2. Int-exp must be an integer between 1 and 255. 


3. If one or more optional clauses are included, one colon (:) is required 
before x-coord. 


Remarks 


1. The optional dev-id identifies the device from which you want to 
accept input. If no identification clause is included, VAX BASIC uses a 
default identification of #0. If an identification clause is included, the 
device specified must have been opened explicitly, or opened by VAX 
BASIC as the default device. 


2. The user-supplied input is interpreted using the transformation with 
the highest priority that contains the point within its viewport. The 
world coordinates of the point are assigned to x-coord and y-coord. 
VAX BASIC assigns the number of the transformation actually used to 
the optional int-var. 
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An initial point can be specified with the optional AT clause. If an 
initial point is specified in the GET POINT statement, this point 
overrides an initial point previously set with the SET INITIAL POINT 
statement. 


The world coordinates you supply for the initial point are interpreted 
with the transformation that is currently selected for output. You can 
specify an alternative transformation for interpreting this point in the 
optional USING TRAN clause. 


The transformation with the highest priority is 1, unless a SET 
INPUT PRIORITY, SET WINDOW, SET VIEWPORT, or SET 
TRANSFORMATION statement has been executed. 


Points accepted with the GET POINT statement in a PICTURE sub- 
program are transformed through the inverse of any transformation 
functions on the DRAW statement that invoked the picture. For exam- 
ple, if a picture is invoked with SCALE(2), device coordinates of input 
points are transformed to world coordinates and then divided by two 
(the inverse of SCALE(2)). 


Points accepted by the LOCATE POINT statement, however, are not 
affected by the transformation functions. See the example for the 
MAT GET POINTS statement for an illustration of this difference. 


Note that a fatal error is signaled when VAX BASIC cannot compute 
the inverse of a user-supplied matrix in a DRAW statement and points 
in a picture are input using the GET or MAT GET statement. 


The optional UNIT clause allows you to specify an alternative means 
of supplying the input. For instance, the position of points can be 
entered with a mouse, or with the keyboard arrow keys. Each of these 
methods of data entry is a different unit. The default unit value for 
int-exp for each input type is 1; the default is used throughout this 
manual. For information about the units available on a particular 
device, see the hardware documentation for that device, as well as the 
VAX GKS documentation. 
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DECLARE LONG which_tran & 
,SINGLE user_x,user_y 

OPEN "RT13" FOR GRAPHICS AS DEVICE #1 

OPEN "VT101" FOR GRAPHICS AS DEVICE #3 

SET WINDOW , TRAN 2 : 0,100,0,100 

SET VIEWPORT , TRAN 2 : 0,0.5,0,0.5 

'+ 

{Use TRAN 1 for initial point 

!- 

GET POINT #3 , AT 50,50 USING TRAN 1 : user_x, user_y ,which_tran 

I+ 

!'Use TRAN 2 (current) for initial point 

f- 

GET POINT #1 , AT 0.5,0.5 : user_x, user_y , which_tran 

IF which_tran <> 2 

THEN GOTO User_help 
END IF 


VAX BASIC Graphics Statements 9-95 


GRAPH 


GRAPH 


The GRAPH statement draws the specified object on all active devices. 
The sequence is determined by the coordinates supplied in the point list. 
Values for the attributes such as color and style use the current settings. 


Format 
POINTS 
GRAPH LINES [ : ] x-coord , y-coord [ ; x-coord, y-coord]... 
\ AREA 


Syntax Rules 


Remarks | 


A GRAPH POINTS statement must include the coordinates for at leas! 


one point. 


A GRAPH LINES statement requires the coordinates for a minimum 
of two points. 


A GRAPH AREA statement requires the coordinates for a minimum o! 
three points. 


The sequence of the objects drawn is determined by the order.of the 
coordinate pairs in the GRAPH statement; the first coordinate pair 
designates the first point, the second pair designates the second point, 
and so on through the end of the coordinate pairs. 


If GRAPH LINES is used to draw a closed figure, the coordinates 
of the first point should be supplied again for the last point. For 
example, to draw a square with GRAPH LINES, you must supply the 
four points of the square and then supply the first point again as the 


fifth point. 
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3. To draw closed areas with the GRAPH AREA statement, you supply 
the same number of points as there are vertices in the polygon. 


4. The coordinates of points in GRAPH statements within a picture 
definition are not affected by the transformations in the DRAW 
statement that invokes the picture. To transform points within a 
picture definition, you must use the PLOT statement. However, when 
you know that transformation functions will not be used, use GRAPH 
rather than PLOT statements, because they are more efficient. 


PROGRAM Tick_tack 


{+ 

‘Set up game board 
f- 

SET LINE STYLE 1 
SET LINE SIZE 2 
SET LINE COLOR 3 


GRAPH LINES 0,0.33; 1,0.33 
GRAPH LINES 0,0.66; 1,0.66 
GRAPH LINES 0.33,0; 0.33,1 
GRAPH LINES 0.66,0; 0.66,1 


t+ 

!Place X markers 

t- 

SET POINT COLOR 1 

SET POINT STYLE 5 

SET POINT SIZE 5 

GRAPH POINTS 0.49,0.82; 0.82,0.82; 0.82,0.49 
'+ 

!Place circle markers 

'- 

SET POINT COLOR 3 

SET POINT STYLE 4 

GRAPH POINTS 0.16,0.82; 0.49,0.49 
i+ 

!Mark next position 

i- 


SET AREA COLOR 1 


.SET AREA STYLE "SOLID" 


GRAPH AREA 0.66,0; 1,0; 1,0.33; 0:66,0.33 
END PROGRAM 
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Output 








ZK-5526-86 


§-98 VAX BASIC Graphics Statements 


GRAPH METAFILE 


GRAPH METAFILE 


The GRAPH METAFILE statement generates graphics output as specified 
in the metafile records. 


Format 
GRAPH METAFILE _ file-spec 


Syntax Rules 


File-spec must be a string expression containing a valid metafile. 


2. If a metafile is opened with an OPEN ... FOR GRAPHICS statement, 
the file-spec in the OPEN ... FOR GRAPHICS statement must match 
the file specification in the GRAPH METAFILE statement. 


Remarks 


1. After a metafile has been created, it can be displayed with the GRAPH 
METAFILE statement. 


2. You can substitute a logical name for the full metafile specification. 


3. A GRAPH METAFILE statement implicitly opens and activates the 
metafile before generating the output. 


4. To create a metafile, you send graphics output from your program to a 
file. You must open the file as device type 2 with the OPEN ... FOR 
GRAPHICS statement. 


5. GRAPH METAFILE displays the output on all activated devices. It is 
not necessary to open a metafile when you display it. 
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Example 1 


PROGRAM create_file 

1+ 

!Open and send output to an output metafile 

t- 

OPEN "(MCKAY]swan.pic" FOR GRAPHICS AS DEVICE #1 , TYPE 2 
EXTERNAL PICTURE swan 

DRAW swan 

END PROGRAM 


Example 2 


PROGRAM draw_file 
t+ 


!Display contents of metafile on default device 
t— 


GRAPH METAFILE " [MCKAY] swan. pic" 
END PROGRAM 
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GRAPH TEXT 


The GRAPH TEXT statement draws the specified characters. The display 
is governed by the current values of the text attributes HEIGHT, JUSTIFY, 
ANGLE, SPACE, EXPAND, FONT and PRECISION. 


Format 
GRAPH TEXT 


Syntax Rules 


Remarks 


[, ] AT x-coord , y-coord: str-exp 


X-coord and y-coord specify the starting position of the text display. 
Str-exp contains the characters to be drawn. 


The text string in str-exp is not wrapped on the terminal screen; text 
that extends beyond the device viewport is not visible. Text is also 
clipped at the world viewport by default. For more information, see 
the SET/ASK CLIP statements. 


The maximum length of the text string is dependent on the setting of 
the various text attributes and the amount of display space available. 
See the example. 


Text attributes are not automatically adjusted according to the trans- 
formation functions on a DRAW statement when text is drawn within 
a picture. However, the text height and text starting point can be 
adjusted with the TRANSFORM function. See the example for the 
TRANSFORM function in this chapter. 


You can format graphics text with the FORMAT$ function. 


After execution of a SET WINDOW statement, you may need to 
change the text height with the SET TEXT HEIGHT statement. 
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Example 
DECLARE STRING CONSTANT text_string = & 
"How much of this will fit on the screen?" 
DECLARE SINGLE def_font, def_height, & 


STRING def_precision 
I+ 
!Store default values 
!- 
ASK TEXT FONT def_font, def_precision 
ASK TEXT HEIGHT def_height 


SET TEXT FONT -8% , "STROKE" 

SET TEXT HEIGHT 0.05 

GRAPH TEXT AT 0.0,0.8 : text_string 
I+ 

Increase the text height 

1- 

SET TEXT HEIGHT 0.1 

GRAPH TEXT AT 0.0,0.4 : text_string 
'+ 

!Restore the default text attributes 
{- 

SET TEXT HEIGHT def_height 

SET TEXT FONT def_font , def_precision 
GRAPH TEXT AT 0.0,0.2 : text_string 
END 
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GRAPH TEXT 


Output 


How much of this text wrt fit on t. 


How much of thi: 


How much of thts text will fft an the scree 


ne eee ne; 
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LOCATE CHOICE 


The LOCATE CHOICE statement accepts a user’s selection from a menu. 


Format 


#dev-id 
LOCATE CHOICE , UNIT int-exp7 int-var 


Syntax Rules 


Remarks 


, INITIAL int-exp2 


When specified, dev-id must be the first clause listed and must be 
preceded by a number sign (#). 


If one or more optional clauses are included, one colon (:) is required 
before int-var. 


Execution of a LOCATE CHOICE statement displays the menu to the 
user. The menu is displayed until the user inputs a menu selection. 
Program control continues with the statement following the LOCATE 
CHOICE statement. 


The menu item input by the user is assigned to int-var. 


The optional dev-id identifies the device from which you want to 
accept input. If no identification clause is included, VAX BASIC uses a 
default identification of #0. If an identification clause is included, the 
device specified must have been opened explicitly, or opened by VAX 
BASIC as the default device. 
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The optional INITIAL clause allows you to specify an initial response 
for the user with int-exp2. This initial value is highlighted in the echo 
area. The features of menu displays are device dependent. 


The INITIAL clause in a LOCATE CHOICE statement overrides the 
INITIAL clause on a previous SET INITIAL CHOICE statement. 


When no INITIAL clause is included, the initial choice established 
with the last SET INITIAL CHOICE statement is used. If no initial 
choice has been set, the initial choice for the device is used. 


The default number of menu items and the initial value vary with 
each device. 


The optional UNIT clause allows you to specify an alternative means 
of supplying the input. For instance, the position of points can be 
entered with a mouse, or with the keyboard arrow keys. Each of these 
methods of data entry is a different unit. The default unit value for 
int-exp for each input type is 1; the default is used throughout this 
manual. For information about the units available on a particular 
device, see the hardware documentation for that device, as well as the 
VAX GKS documentation. 


PROGRAM tax_data 
EXTERNAL SUB More_questions 
DECLARE LONG marital_status, & 


STRING form 


OPEN "RT75" FOR GRAPHICS AS DEVICE #1 
SET INITIAL CHOICE #1 , LIST 


("Single", 
"Divorced", 
"Widowed", 
"Married", 
"Other") 


SPFeeree eer 
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1+ 

!Display menu, set a new initial choice & accept input 
t- 

LOCATE CHOICE #1 , INITIAL 5 : marital_status 

SELECT marital_status 


CASE = 1% !Single 
CALL More_questions 
CASE = 4%, !Married 


Form = "joint" 
2% OR 3% !Divorced or widowed 
Form = "long" 
CASE ELSE 
CALL More_questions 


CASE 


END SELECT 


END PROGRAM 


(Oe 


Output 


Single 
Divorced 
Widowed 


Married 





5 are ve cl, 
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LOCATE POINT 


A LOCATE POINT statement accepts a single point input by a user. 


Format 


LOCATE POINT 


syntax Rules 


temarks 


#dev-id 
, UNIT int-exp7 : 
_ , AT x-coord1, y-coord! [ USING TRAN int-exp2] 


x-coord2, y-coord2 [ , int-var ] 


When specified, dev-id must be the first clause listed and must be 
preceded by the number sign (#). 


Int-exp2 must be an integer between 1 and 255. 


If one or more optional clauses are included, one colon (:) is required 
before x-coord2. 


The world coordinates of the user-supplied input are assigned to the 
variables x-coord2 and y-coord2. 


The optional dev-id identifies the device from which you want to 
accept input. If no identification clause is included, VAX BASIC uses a 
default identification of #0. If an identification clause is included, the 
device specified must have been opened explicitly, or opened by VAX 
BASIC as the default device. 
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An initial point can be specified in the optional AT clause. VAX BASIC 
uses the current transformation for output to interpret the world co- 
ordinates of this point. You can specify an alternative transformation 
for interpreting this initial point in the optional USING TRAN clause. 
If an initial point is specified in the LOCATE POINT statement, this 
point overrides an initial point previously set with the SET INITIAL 
POINT statement. 


The transformation with the highest priority is 1, unless a SET 
WINDOW, SET VIEWPORT, or SET TRANSFORMATION statement 
has been executed. See also the SET INPUT PRIORITY statement. 


If multiple transformations are defined, the user-supplied point is 
evaluated using the transformation with the highest input priority 
of all transformations that contain the input point in their viewport. 
VAX BASIC assigns the actual number of the transformation used to 
optional int-var. 


The initial point is indicated to the user with a device dependent 
prompt such as a tracking plus sign. The user can move the prompt 
with the arrow keys or a mouse to indicate a new point. To enter a 
selected point, the user presses RETURN or performs a similar activity 
The actual actions required are device dependent. 


The program waits until the user indicates that input is complete. 
Program execution continues with the statement lexically after the 
LOCATE POINT statement. 


Unlike points accepted by the GET POINT statement, points accepted 
by a LOCATE POINT statement within a picture are not affected by 
any transformation functions in the DRAW statement that invoked the 
picture. See the example for the MAT GET POINTS statement for an 
illustration of this difference. 


The optional UNIT clause allows you to specify an alternative means 
of supplying the input. For instance, the position of points can be 
entered with a mouse, or with the keyboard arrow keys. Each of thes: 
methods of data entry is a different unit. The default unit value for 
int-exp1 for each input type is 1; the default is used throughout this 
manual. For information about the units available on a particular 
device, see the hardware documentation for that device, as well as thi 
VAX GKS documentation. 
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OPTION TYPE = EXPLICIT 
EXTERNAL PICTURE boat (SINGLE, ) 
DECLARE LONG alt_tran,which_tran, & 
SINGLE user_x, user_y 
t+ 
!Specify alternative transformation for initial point 
t- 
alt_tran = 2 
I+ 
'Request coordinate pair from user & set initial point 
t- 
LOCATE POINT , AT 50,50 USING TRAN alt_tran : user_x, user_y , which_tran 
!+ 
!Use input coordinates as starting point for a picture invocation 
'- 


DRAW boat (user_x,user_y) 


END 
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LOCATE STRING 


The LOCATE STRING statement accepts a user’s string input. 


Format 
#dev-id 
LOCATE STRING _ UNIT int-exp : str-var 
, INITIAL str-exp 
Syntax Rules 

1. When specified, dev-id must be the first clause listed and must be 
preceded by the number sign (#). 

2. If one or more optional clauses are included, one colon (:) is require 
before str-var. 

Remarks 

1. The string supplied by the user is assigned to str-var. 

2. The optional dev-id identifies the device from which you want to 
accept input. If no identification clause is included, VAX BASIC uses 
default identification of #0. If an identification clause is included, th: 
device specified must have been opened explicitly, or opened by VA: 
BASIC as the default device. 

3. The optional INITIAL clause allows you to specify an initial string fc 


the user. This initial string is displayed within the string echo area. 
The user can enter this initial string, or an alternative. The initial 
string specified in a LOCATE STRING statement overrides an initial 
string specified in a SET INITIAL STRING statement. 
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4. When no INITIAL clause is included, the initial string in the last SET 
INITIAL STRING statement is used. If no initial string has been set, 
the default string for the device is used (usually the null string). 


5. VAX BASIC appends the user-supplied string to the initial string you 
specify in a LOCATE STRING or a SET INITIAL STRING statement. 
If the user accepts the initial string with a null response, str-var 
contains only the initial string. Depending on the device, it may be 
possible for a user to delete the initial string by pressing CTRL/U or 
the DELETE key. You can use the VAX BASIC string functions to 
locate the exact user input. 


6. The optional UNIT clause allows you to specify an alternative means 
of supplying the input. For instance, the position of points can be 
entered with a mouse, or with the keyboard arrow keys. Each of these 
methods of data entry is a different unit. The default unit value for 
int-exp for each input type is 1; the default is used throughout this 
manual. For information about the units available on a particular 
device, see the hardware documentation for that device, as well as the 
VAX GKS documentation. 


OPTION TYPE = EXPLICIT 
DECLARE STRING init_string, user_string, response 
init_string = "YES" 
LOCATE STRING , INITIAL init_string : user_string 
{+ 
!'Check if user responded with a <CR> 
t- 
IF user_string = init_string 
THEN response = init_string 
GOTO print_it_out 
ELSE GOTO extract_string 
END IF 
extract_string: 
I+ 
!'Check if all of init_string has been deleted or not 
t- 
IF LEFT$(user_string,3) = LEFT$(init_string,3) 
THEN response = RIGHT$(user_string, 4) 
ELSE response = user_string 
END IF 
print_it_out: 
PRINT “User entered '" + response + "'" 
END 
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[OCATE VALUE 


The LOCATE VALUE statement accepts a numeric value input by a user. 


Format 
#dev-id | 
UNIT int-ex, 
LOCATE VA ' p |- 
OCATE VALUE | "RANGE real-exp! TO realexp2 ) ° ( | var 
, INITIAL real-exp3 
Syntax Rules 


1. When specified, dev-id must be the first clause listed and must be 
preceded by the number sign (#). 


2. Real-exp1 must be less than real-exp2 in the optional RANGE clause. 


3. Real-exp3 must be within the optional range when specified. If no 
RANGE clause is included, real-exp3 must be within the default range 


4. You can include one or more optional clauses. 


5. A colon must precede real-var when one or more optional clauses are 
present. 
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The value input by the user is assigned to real-var. 


The optional dev-id identifies the device from which you want to 
accept input. If no identification clause is included, VAX BASIC uses a 
default identification of #0. If an identification clause is included, the 
device specified must have been opened explicitly, or opened by VAX 
BASIC as the default device. 


The optional RANGE clause allows you to specify the extent of accept- 
able values to the user. Intermediate values are scaled proportionately. 


The RANGE clause specifies the lowest and highest acceptable input. 
The user-supplied value and the initial value must be within this 
range. VAX BASIC signals the run-time error ILLINIVAL, “illegal 
initial value” (ERR = 284), when the initial value is not within the 
specified range. 

When no RANGE clause is included, the range in the last SET 
INITIAL VALUE statement is used. If no initial values have been 
set, the default range is 0 to 1. 


The optional INITIAL clause allows you to specify an initial value 
for the user. This initial value is displayed within the specified range 
in the echo area. The initial value and range specified in a LOCATE 
VALUE statement override the value and range specified in a SET 
INITIAL VALUE statement. 


The program waits until the default response or an alternative value 

is entered at the terminal. To enter a selected value, the user presses 
RETURN or performs a similar activity. The actual actions are device 
dependent. 


The optional UNIT clause allows you to specify an alternative means 
of supplying the input. For instance, the position of points can be 
entered with a mouse, or with the keyboard arrow keys. Each of these 
methods of data entry is a different unit. The default unit value for 
int-exp for each input type is 1; the default is used throughout this 
manual. For information about the units available on a particular 
device, see the hardware documentation for that device, as well as the 
VAX GKS documentation. 


For an illustration of the VALUE echo and prompt, see the SET 
INITIAL VALUE statement. 
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EXTERNAL SUB small_claims(SINGLE) , 
night_court (SINGLE) , 
probate 
DECLARE SINGLE limiti1, limit2, your_number 
limiti = 0 
limit2 = 10 
LOCATE VALUE , RANGE limiti TO limit2 
, INITIAL 2.5 
> your_number 
SELECT your_number 
CASE < 2.5 
CALL small_claims(your_number) 
CASE = 2.5 
CALL night_court (your_number) 
CASE > 2.5 
CALL probate 
END SELECT 
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MAT GET POINTS 


The MAT GET POINTS statement accepts one or more points input by a 
user. 


ormat 


#dev-id 
, UNIT int-exp7 
matory , COUNT int-var7 
, AT x-coord, y-coord [ USING TRAN int-exp2 ] 


x-array, y-array [ , int-var2] 


iyntax Rules 


1. When specified, dev-id must be the first clause listed and must be 
preceded by the number sign (#). 


2. With the MAT statement, specify only the array name; do not use 
parentheses to indicate the whole array. 


3. X-array and y_array must be one-dimensional arrays that contain only 
integer or real data types. Virtual arrays are not valid. 


4. Int-exp2 must be an integer between 1 and 255. 


5. If one or more optional clauses are included, one colon (:) is required 
before x-array. 
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Remarks 


The optional dev-id identifies the device from which you want to 
accept input. If no identification clause is included, VAX BASIC uses ¢é 
default identification of #0. If an identification clause is included, the 
device specified must have been opened explicitly, or opened by VAX 
BASIC as the default device. 


When multiple transformations are defined, the user-supplied input 
is interpreted with the transformation with the highest priority that 
contains all the points input by the user. The world coordinates of the 
user-supplied points are assigned to x-array and y-array. VAX BASIC 
assigns the number of the transformation used to int-var2. See also 
the SET INPUT PRIORITY statement. 


An initial point can be specified in the optional AT clause. VAX 
BASIC uses the current output transformation to interpret the world 
coordinates of this point for display on the user’s screen. You can 
specify an alternative transformation for interpreting this initial point 
by including an optional USING TRAN clause. If an initial point is 
specified in a MAT GET POINTS statement, this point overrides an 
initial point previously set with a SET INITIAL MULTIPOINT or SET 
INITIAL POINT statement. 


The optional COUNT clause allows you to find out how many points 
the user actually entered. If a user enters more points than the input 
arrays can contain, VAX BASIC discards the extra points and the user 
cannot retrieve these values; however, int-var1 still retains the actual 
number entered. When an unknown number of points is input and 
you want to display these points, you need to examine int-var1 before 
using this number in the MAT GRAPH or MAT PLOT statements . 
you use for related output. The following example shows one way of 
ensuring that the COUNT clause is valid for the output statement. 
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Example 


DECLARE LONG CONSTANT in_max = 12 

DECLARE LONG how_many 

DIM SINGLE in_x(1 TO in_max),in_y(1 TO in_max) 

MAT GET POINTS , COUNT how_many : in_x, in_y 

IF how_many > in_max 

THEN GRAPH TEXT AT 0,0.9: "You can only input" 

GRAPH TEXT AT 0,0.8: STR$(in_max) + " points. Your" 
GRAPH TEXT AT 0,0.7: “extra points have been discarded." 
how_many = in_max 

END IF 

MAT GRAPH POINTS , COUNT how_many : in_x, in_y 


5. The optional UNIT clause allows you to specify an alternative means 
of supplying the input. For instance, the position of points can be 
entered with a mouse, or with the keyboard arrow keys. Each of these 
methods of data entry is a different unit. The default unit value for 
int-exp1 for each input type is 1; the default is used throughout this 
manual. For information about the units available on a particular 
device, see the hardware documentation for that device, as well as the 
VAX GKS documentation. 


6. Points accepted with the MAT GET POINTS statement in a PICTURE 
subprogram are transformed through the inverse of any transformation 
functions on the DRAW statement that invoked the picture. Points 
accepted by the MAT LOCATE POINTS statement, however, are not 
affected by the transformation functions. 


The following example illustrates the difference between the MAT GET 
POINTS and MAT LOCATE POINTS statements. The points accepted 
by the GET statement are scaled according to the transformation function 
in the DRAW statement; therefore, these points are displayed within the 
cheese outline. The points accepted by the LOCATE statement are not 
scaled along with the cheese outline; therefore, the points are not all 
displayed within the outline. 


EXTERNAL PICTURE get_the_points & 
, locate_the_points 


!Circles for the holes in the cheese 
SET POINT STYLE 4 

DRAW get_the_points WITH SCALE(1/2) 
SLEEP 5% 

CLEAR 
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MAT GET POINTS 


DRAW locate_the_points WITH SCALE(1/2) 
END 


PICTURE swiss_cheese 
DECLARE LONG counter 
DIM SINGLE outline_x(9) , outline_y(9) 
DATA 0.25,0.6, 0.25,0.125, 0.75,0.125, 0.75,0.6, 0.25,0.6, & 
0.95,0.75, 0.75,0.6, 0.95,0.75, 0.95,0.275, 0.75,0.125 
READ outline_x(counter) ,outline_y(counter) FOR counter = 0 TO 9 
MAT PLOT LINES outline_x, outline_y 
END PICTURE 


PICTURE get_the_points 

EXTERNAL PICTURE swiss_cheese 

DECLARE LONG CONSTANT input_max = 12 

DECLARE LONG how_many 

DIM SINGLE get_xholes(input_max) ,get_yholes (input_max) 

DRAW swiss_cheese 

MAT GET POINTS ,COUNT how_many : get_xholes, get _yholes 

IF how_many > (input_max + 1) 

THEN how_many = input_max + 1 

END IF 

MAT GRAPH POINTS , COUNT how_many : get_xholes, get_yholes 
END PICTURE 


PICTURE locate_the_points 

EXTERNAL PICTURE swiss_cheese 

DECLARE LONG CONSTANT input_max = 12 

DECLARE LONG how_many 

DIM SINGLE locate_xholes(input_max) , locate_yholes (input_max) 

DRAW swiss_cheese 

MAT LOCATE POINTS , COUNT how_many : locate_xholes, locate_yholes 

IF how_many > (input_max + 1) 

THEN how_many = input_max + 1 

END IF 

MAT GRAPH POINTS , COUNT how_many : locate_xholes, locate_yholes 
END PICTURE 
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MAT GET POINTS 


Output from Get_the_points: 





© CO 
O 
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Output from Locate_the_points: 
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MAT GRAPH 


The MAT GRAPH statement draws graphics output specified by the worl: 
coordinate points contained in arrays. The output is drawn on all active 

devices. Values for graphics attributes such as color and style depend on 
the current settings. 


Format 


POINTS 
MAT GRAPH LINES [, COUNT int-exp : | x-array, y-array 
AREA 


Syntax Rules 


1. With the MAT statement, specify only the array name; do not use 
parentheses to indicate the whole array. 


2. Both x-array and y-array must be one-dimensional arrays containing 
integer or real data types. Virtual arrays are not valid. 


3. Int-exp cannot be greater than the number of elements in the coordi- 
nate arrays. 


4. A MAT GRAPH POINTS statement must include the coordinates for 
at least one point with each coordinate in the appropriate array. 


5. A MAT GRAPH LINES statement requires a minimum of two points. 


6. A MAT GRAPH AREA statement requires a minimum of three coordi 
nate pairs. 
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MAT GRAPH 


Remarks 


1. Points specified in arrays must begin in the element with the low- 
est subscript. An optional COUNT clause allows you to display a 
specified number of the points described in the array elements. If no 
COUNT clause is included, all of the points specified in the arrays are 
displayed. 

2. The sequence of objects drawn is determined by the order of the 
coordinates in the arrays in the MAT GRAPH statement; the first pair 
of coordinates supplied in both arrays designates the first point, the 
second pair designates the second point, and so on through the end of 
the arrays. 


3. If MAT GRAPH LINES is used to draw a closed figure, the coordinates 
of the first point should be supplied again for the last point. For 
example, to draw a square with MAT GRAPH LINES, you must 
supply the four points of the square and then supply the first point 
again as the fifth point. 


4. To draw closed areas with the MAT GRAPH AREA statement, you 
supply the same number of points as there are vertices in the polygon. 


5. The coordinates of points in MAT GRAPH statements within a picture 
definition are not affected by the transformations specified in the 
DRAW statement that invoked the picture. To transform points 
within a picture definition, you must use the MAT PLOT statement. 
However, when you know that transformation functions will not be 
used, use GRAPH rather than PLOT statements, because they are 
more efficient. 


PROGRAM letter_w 
DECLARE LONG counter 
DIM SINGLE x_coords (6) , y_coords (6) 
DATA 0.24,0.75, 0.3,0.45, 0.375,0.125, 0.5,0.55, & 
0.625,0.125, 0.7,0.45, 0.76,0.75 
READ x_coords(counter),y_coords(counter) FOR counter = 0% TO 6% 


!For illustration, the same coords are used 
‘in each of the following MAT statements 
SET VIEWPORT ,TRAN 1 :0,0.5,0,0.5 

MAT GRAPH POINTS x_coords, y_coords 
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MAT GRAPH 


SET VIEWPORT ,TRAN 2 : 0,0.5,0.5,1 
MAT GRAPH LINES x_coords, y_coords 
SET VIEWPORT ,TRAN 3 : 0.5,1,0.5,1 
MAT GRAPH AREA x_coords, y_coords 

END PROGRAM 


Output 
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MAT LOCATE POINTS 


The MAT LOCATE POINTS statement acres one or more points input 


by a user. 

Format 
#dev-id 
, UNIT int-exp7 

MAT LOCATE POINTS "COUNT int-varl 
, AT x-coord, y-coord [ USING TRAN int-exp2 ] 
x-array, y-array [ , int-var2] 
Syntax Rules 


1. When specified, dev-id must be the first clause listed and must be 
preceded by the number sign (#). 


2. With the MAT statement, specify only the array name; do not use 
parentheses to indicate the whole array. 


3. X-array and y_array must be one-dimensional arrays that contain only 
integer or real data types. Virtual arrays are not valid. 


4. Int-exp2 must be an integer between 1 and 255. 


5. If one or more optional clauses are included, one colon (:) is required 
before x-array. 
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MAT LOCATE POINTS 


Remarks 


1. The optional dev-id identifies the device from which you want to 
accept input. If no identification clause is included, VAX BASIC uses a 
default identification of #0. If an identification clause is included, the 
device specified must have been opened explicitly, or opened by VAX 
BASIC as the default device. 


2. When multiple transformations are defined, the user-supplied input 
is interpreted with the transformation with the highest priority that 
contains all the points input by the user. The world coordinates of the 
user-supplied points are assigned to x-array and y-array. VAX BASIC 
assigns the number of the transformation used to int-var2. See also 
the SET INPUT PRIORITY statement. 


3. An initial point can be specified in the optional AT clause. VAX 
BASIC uses the current output transformation to interpret the world 
coordinates of this point for display on the user’s screen. You can 
specify an alternative transformation for interpreting this initial point 
by including an optional USING TRAN clause. If an initial point is 
specified in a MAT LOCATE POINTS statement, this point overrides 
an initial point previously set with a SET INITIAL MULTIPOINT or 
SET INITIAL POINT statement. 


4. The optional COUNT clause allows you to find out how many points 
the user actually entered. If a user enters more points than the input 
arrays can contain, VAX BASIC discards the extra points and the user 
cannot retrieve these values; however, int-varl1 still retains the actual 
number entered. When an unknown number of points are input and 
you want to display these points, you need to examine int-var1 before 
using this number in the MAT GRAPH or MAT PLOT statements 
you use for related output. The example at the end of this statement 
shows one way of ensuring that the COUNT clause is valid for the 
output statement. 


5. The optional UNIT clause allows you to specify an alternative means 
of supplying the input. For instance, the position of points can be 
entered with a mouse, or with the keyboard arrow keys. Each of these 
methods of data entry is a different unit. The default unit value for 
int-exp1 for each input type is 1; the default is used throughout this 
manual. For information about the units available on a particular 
device, see the hardware documentation for that device, as well as the 
VAX GKS documentation. 
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6. Points accepted with the MAT LOCATE POINTS statement in a 
PICTURE subprogram are not affected by any transformation functions 
on the DRAW statement that invoked the picture. Points accepted by 
the MAT GET POINTS statement, however, are transformed by the 
inverse of the transformation functions. See the MAT GET POINTS 
statement for an example illustrating this difference. 


DECLARE LONG CONSTANT in_max = 12 

DECLARE LONG how_many 

DIM. in_x(in_max) , in_y (in_max) 

MAT LOCATE POINTS , COUNT how_many : in_x, in_y 

IF how_many > in_max 

THEN GRAPH TEXT AT 0,0.9: "You can only input" 

GRAPH TEXT AT 0,0.8: STR$(in_max) + " points. Your" 
GRAPH TEXT AT 0,0.7: "extra points have been discarded." 
how_many = in_max 

END IF 

SET POINT COLOR 2 

MAT GRAPH POINTS , COUNT how_many : in_x, in_y 
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MAT PLOT 


The MAT PLOT statement draws graphics output specified by the world 

_ coordinate points contained in arrays. Points drawn with the MAT PLOT 
statement within a picture are affected by the transformation functions 
included in the DRAW statement that invokes the picture. The output is 
drawn on all active devices. Values for graphics attributes such as color 
and style depend on the current settings. 


Format 


-  ( POINTS | 
MAT PLOT LINES => /, COUNT int-exp: | x-array, y-array 
AREA 


Syntax Rules 


1. With the MAT statement, specify only the array name; do not use 
parentheses to indicate the whole array. 


2. Both x-array and y-array must be one-dimensional arrays containing 
integer or real data types. Virtual arrays are not valid. 


3. Int-exp cannot be greater than the number of elements in the coordi- 
nate arrays. 


4. A MAT PLOT POINTS statement must include the coordinates for at 
least one point with each coordinate in the appropriate array. 


5. A MAT PLOT LINES statement requires a minimum of two points. 


6. A MAT PLOT AREA statement requires a minimum of three coordi- 
nate pairs. 
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Remarks 


Example 


MAT PLOT 


1. Points specified in arrays must begin in the element with the lowest 
subscript. An optional COUNT clause allows you to display a speci- 
fied number of the points described in the arrays. If no COUNT clause 
is included, all of the points specified in the arrays are displayed. 


2. The sequence of objects drawn is determined by the order of the 
coordinates in the arrays in the MAT PLOT statement; the first pair 
of coordinates supplied in both arrays designates the first point, the 
second pair designates the second point, and so on through the end of 
the arrays. 


3. If MAT PLOT LINES is used to draw a closed figure, the coordinates 
of the first point should be supplied again for the last point. For 
example, to draw a square with MAT PLOT LINES, you must supply 
the four points of the square and then supply the first point again as 
the fifth point. 


4. To draw closed areas with the MAT PLOT AREA statement, you 
supply the same number of points as there are vertices in the polygon. 


5. The coordinates of points in MAT PLOT statements within a picture 
definition are affected by the transformations in the DRAW statement 
that invokes the picture. However, when you know that transfor- ° 
mation functions will not be used, use GRAPH rather than PLOT 
statements, because they are more efficient. 


PROGRAM letter_w 


EXTERNAL PICTURE area_w(SINGLE DIM (), SINGLE DIM ()), & 
lines_w(SINGLE DIM (), SINGLE DIM ()), & 
points_w(SINGLE DIM (), SINGLE DIM ()) 

DECLARE LONG counter —— 

DIM SINGLE x_coords(6) ,y_coords(6) 

SET VIEWPORT ,TRAN 1 :0,0.5,0,0.5 

SET VIEWPORT ,TRAN 2 : 0,0.5,0.5,1 

SET VIEWPORT ,TRAN 3 : 0.5,1,0.5,1 

DATA 0.24,0.75, 0.3,0.45, 0.375,0.125, 0.5,0.55, & 


0.625 ,0.125, 0.7,0.45, 0.76,0.75 
READ x_coords(counter) ,y_coords(counter) FOR counter = 0% TO 6% 


SET TRANSFORMATION 1 
DRAW points_w(x_coords() ,y_coords()) WITH SCALE(0.5) 
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MAT PLOT 


SET TRANSFORMATION 2 
DRAW lines_w(x_coords() ,y_coords()) WITH SCALE(0.5) 


SET TRANSFORMATION 3 

SET AREA STYLE "SOLID" 

DRAW area_w(x_coords() ,y_coords()) WITH SCALE(0.5) 
END PROGRAM 


PICTURE points_w(SINGLE x_coords(),y_coords()) 
MAT PLOT POINTS x_coords, y_coords 
END PICTURE 


PICTURE lines_w(SINGLE x_coords() ,y_coords()) 
MAT PLOT LINES x_coords, y_coords 
END PICTURE 


t+ 
!This picture uses MAT GRAPH rather than MAT PLOT 


'See the output of area_w compared to points_w and lines_w 
1- 


PICTURE area_w(SINGLE x_coords(),y_coords()) 
MAT GRAPH AREA x_coords, y_coords 
END PICTURE 


Output 
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PEN ... FOR GRAPHICS 


The OPEN ... FOR GRAPHICS statement opens and activates the 
specified device for graphics input or output. 


prmat 


OPEN { hice } FOR GRAPHICS AS / DEVICE ] #dev-id [, TYPE dev-type ] 


yntax Rules 


pmarks 


Dev-name can be a string expression or a quoted string representing a 
logical name for a device. 


File-spec must be a valid metafile. 
You must supply the number sign (#) with dev-id. 


Dev-type must be a valid integer expression representing a device 
supported by VAX GKS and must correspond to the actual device (or 
metafile) specified in dev-name. See Table 9-1 in this section for a list 
of supported device types. 


If only the default device is used, you need not use the OPEN ... 
FOR GRAPHICS statement. When graphics output statements are 
executed and no device has been opened, VAX BASIC opens the 
default device. The default device is opened with the equivalent of 
the following statement: 


OPEN "" FOR GRAPHICS AS DEVICE #0 
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OPEN ... FOR GRAPHICS 


VAX BASIC opens the default device as a monochrome VT240 (devic 
type 14), unless an alternative device type has been assigned to the 
logical name GKS$WSTYPE. To find out if GKS$WSTYPE has been 
assigned system-wide, use the following command: 


$ SHOW LOGICAL GKS$WSTYPE 


If a device type has been assigned to GKS$WSTYPE, VAX BASIC use 
this type as the default device; however, if no device type has been 
assigned, VAX BASIC assumes the device is a monochrome VT240. 


To assign a specific device type as your own default, use the DCL 
command ASSIGN. The following command informs VAX GKS 
that you are using a VT240 terminal with the color option (device 
type 13). This assignment overrides any system value assigned to 
GKS$WSTYPE. 


$ ASSIGN 13 GKS$WSTYPE 


2. An OPEN ... FOR GRAPHICS statement implicitly activates the 
identified device. 


3. Table 9-1 in this section lists the possible values for dev-type. This 
list is complete up to the print date on this manual. For up-to-date 
information, consult the VAX GKS documentation. 


4. When an OPEN ... FOR GRAPHICS statement specifies a device 
that is already open, VAX BASIC closes the device, then reopens it 
with the specifications in the most recent OPEN ... FOR GRAPHIC! 
statement. 


5. The dev-id specified in an OPEN ... FOR GRAPHICS statement is 
not related to the channels specified in the OPEN statement for file 
I/O. For example, you could open a file on channel #1 and open a 
graphics device as #1. Channel #1 and device #1 are independent o. 
each other. 


6. If you open a device that has color index values that are not contigu- 
ous, VAX BASIC issues an error message. Results from the ASK MA: 
COLOR statement are unpredictable on such a device. 


7. For information on opening a metafile, see the GRAPH METAFILE 
statement. 


8. Information that is specific to VAXstations and to VT125 and VT240 
terminals is listed in Appendix B. 
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Table 9-1: 


Device Type 
0 
2 
3 
10 
11 
2 
13 
14 
15 
31 


OZ 
33 
41 


51 
52 
70 
72 


OPEN ... FOR GRAPHICS 


Supported Device Types 


Supported Device! 
Default device type 
Output metafile 

Input metafile 

VT125 output only 
VT125 with color 
VT125 black and white 
VT240 with color 
VT240 black and white 
LCPO1 printer 


LA34 with graphics option 
LA100 
LA210 


LA50 with 2:1 aspect ratio 
LA12 


VAxstation I 
VAXstation II monochrome 
VAXstation II/GPX color 


LVP16 color plotter (8-1/2 by 11 paper) 
LVP16 (11 by 17 paper) 

Tektronix 4014 output only 

Tektronix 4014 





Mt is possible that the device you use is not on this list but has been adapted to take advantage of 
VAX GKS. If this is the case, you should refer to both the hardware and the VAX GKS documentation 
and use caution in all device-specific clauses in your applications. This list was complete when this 
manual went to print; see the VAX GKS documentation for the latest information about supported 


devices. 
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OPEN ... FOR GRAPHICS 





! 
idpen a VAXstation II 

le 

OPEN “VTA24:" FOR GRAPHICS AS DEVICE #1 , TYPE 41 
‘ 

\Gpen a terminal as the default device type 

{- 

OPEN "“my_term" FOR GRAPHICS AS DEVICE #2 

! 

‘Dea an output metafile 


OPEN "meta.pic" FOR GRAPHICS AS DEVICE #3 , TYPE 2 
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PICTURE 


7IC TURE 


A PICTURE subprogram defines a graphics display and can be invoked 
with the DRAW statement. The PICTURE statement marks the start of a 
picture definition. 


‘ormat 
PICTURE pic-name [(param-list)] 


Statement 
[statement] 


END PICTURE 


byntax Rules 


1. Pic-name must be a valid VAX BASIC identifier and must not be 
the same as an identifier for a SUB or FUNCTION subprogram or a 
PROGRAM unit. 

2. Parameters in the param-list must agree in number and data type with 
the parameters in a picture invocation (a DRAW statement). 
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PICTURE 


Remarks 


A definition of a picture must be delimited by the PICTURE and END 
PICTURE statements. 


Statements within a picture can invoke other procedures. 


Pictures can be recursive; a picture can include a DRAW statement 
that invokes itself. These DRAW statements can be either within the 
picture or within a called subprogram. 


Statements that affect the boundaries of windows and viewports as 
well as statements that affect the clipping status are not valid within 
a picture. Errors are signaled if these statements are lexically within 
a picture definition, or if the statements are executed in a subprogram 
called from a picture. Invalid statements include the following: 


e SET CLIP 

e SET DEVICE VIEWPORT 

e SET DEVICE WINDOW 

e SET INPUT PRIORITY 

e SET TRANSFORMATION 

e SET VIEWPORT 

e SET WINDOW 

Pictures are invoked with the DRAW statement and can be rotated, 
scaled, shifted, tilted, and otherwise modified by transformation 


functions included in the DRAW statement. For more information 
about invoking pictures, see the DRAW statement. 


Transformation functions in DRAW statements within a picture are 
cumulative. That is, when a second or subsequent picture is invoked 
within a picture definition, the transformations from all of the relevan 
DRAW statements are applied to the points generated by the second o 
subsequent picture. For example, in the following picture, the picture 
nest2 is invoked with a DRAW statement equivalent to DRAW WITH 
SCALE(2,1) * SHIFT(50,0). 
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PICTURE 


Example 


PICTURE nest 1 
EXTERNAL nest2 


DRAW nest2 WITH SCALE(2,1) 
END PICTURE 
t+ 


!Invoke picture nesti 
'- 


DRAW nesti WITH SHIFT(50,0) 


7. When graphics output statements using GRAPH or MAT GRAPH are 
contained within a picture, the points displayed are not affected by 
the transformation functions in the DRAW statement that invokes the 
picture. Output displayed with the PLOT and MAT PLOT statements, 
on the other hand, is affected by the transformation functions. See the 
GRAPH and PLOT statements for more information. 


8. When graphics input statements using LOCATE are contained within a 
picture, the points entered are not affected by the transformation func- 
tions in the DRAW statement that invokes the picture. Input points 
accepted by the GET statement are affected by the transformation 
functions. For more information, see the LOCATE and GET POINTS 
statements, as well as the MAT GET POINTS statement. 


9. For more examples of pictures, see Chapter 6 in this manual. See 
Chapter 7 for information about accepting input within picture defini- 
tions. 


EXTERNAL PICTURE square (LONG) 

DECLARE LONG width 

SET WINDOW 0,100,0,100 

DRAW square(width) FOR width = 60 TO 10 STEP -10 
END 
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PICTURE 


PICTURE square(LONG width) 

DECLARE SINGLE x_top_left,y_top_left, & 
x_top_right ,y_top_right, & 
x_bottom_right ,y_bottom_right, & 
x_bottom_left,y_bottom_left 

x_top_left = 50 - width/2 

y_top_left = 50 + width/2 

x_top_right = y_top_left 

y_top_right = y_top_left 

x _bottom_right = x_top_right 

y_bottom_right = x_top_left 

x_bottom_left = x_top_left 

y_bottom_left = y_bottom_right 


PLOT LINES : x_top_left, y_top_left; 
x_top_right, y_top_right; 
x_bottom_right ,y_bottom_right ; 
x_bottom_left ,y_bottom_left; 
x_top_left ,y_top_left 


R & & & 


END PICTURE 


Output 
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PLOT 


OT 


The PLOT statement draws the specified graphics object on all active 
devices. Values for graphics attributes such as color and style use the 
current settings. Graphics objects displayed with PLOT from within 
a picture are affected by the transformation functions specified on the 
DRAW statement that invokes the picture. 


mat 


POINTS 
LOT LINES [ : ] x-coord , y-coord [ ; x-coord, y-coord ]... 
AREA 


itax Rules 


1. A PLOT POINTS statement must include the coordinates for at least 
one point. 

2. A PLOT AREA statement must include the coordinates for at least 
three points. 


3. The last point specified in a PLOT LINES statement can be followed 
by an optional semicolon (see the remarks below). 


narks 


1. The sequence of drawing the objects is determined by the order of the 
coordinate pairs presented in the PLOT statement; the first coordinate 
pair designates the first point, the second pair designates the second 
point, and so on through the end of the coordinate pairs. 
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PLOT 


A “beam of light” can be left on if you add a semicolon after the 
last point specified in a PLOT LINES statement. When this beam « 
light is left on, a line will be drawn from this point to the next poi 
specified in a subsequent PLOT LINES statement. For instance, th 
first PLOT LINES statement in the following example leaves the be 
of light on and a line is drawn between points 50,50 and 75,75. T! 
beam of light is then turned off because no semicolon is present af 
the second PLOT LINES statement. 


PLOT LINES 50,50; !beam is left on 


PLOT LINES 75,75 !beam is turned off 


The output from PLOT LINES statements that leave the beam on 
is not actually displayed until the beam is switched off with the 
execution of any graphics output statement other than PLOT LINE 
with a semicolon. If no further graphics output statement is execut 
the output is displayed when program execution terminates. 


A PLOT LINES statement with no points supplied switches off the 
beam of light. 


If PLOT LINES is used to draw a closed figure, the coordinates of | 
first point should be supplied again for the last point. For example 
to draw a square with PLOT LINES, you must supply the four poi 
of the square and then supply the first point again as the fifth poir 
These points can be supplied one at a time (such as in a loop), or « 
after the other in the same statement. 


To draw closed areas with the PLOT AREA statement, you supply 
same number of points as there are vertices in the polygon. 


The coordinates of points in PLOT statements within a picture defi 
tion are affected by the transformations in the DRAW statement th 
invokes the picture. However, when you know that transformatio1 
functions will not be used, use GRAPH rather than PLOT statemer 
because they are more efficient. 
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PLOT 


OPTION TYPE = EXPLICIT 

DECLARE SINGLE counter 

SET WINDOW 0,2*PI,-1,1 

SET LINE SIZE 5 

FOR counter = 0 TO 2¥*PI STEP 0.1 
{Supply points 1 at a time 
!leave beam on to connect to next point 
PLOT LINES counter, SIN(counter) ; 

NEXT counter 

'+ 

!Complete the curve 

t- 

PLOT LINES 2 * PI,SIN(2 * PI) 

END 


Output 





a ee 
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RESTORE GRAPHICS 


The RESTORE GRAPHICS statement clears the current values for all 
attributes and input types, and restores the default values as at the star 
program execution. 


Format 
RESTORE GRAPHICS 


Syntax Rules 
None. 
Remarks 


1. Executing a RESTORE GRAPHICS statement closes all open device 


When a RESTORE GRAPHICS statement is executed, all values 
for output attributes, characteristics of input types, and any device 
defaults are restored to their values at the start of program executic 


Example 
Declarations: 


trapper = CTRLC 
WHEN ERROR USE cntrc_trap 
Start_up: 
OPEN "RT23" FOR GRAPHICS AS DEVICE #3 


END WHEN 
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RESTORE GRAPHICS 


HANDLER cntrc_trap 
!'Test if user entered CTRL/C 
IF ERR = 28% 
‘Restore original attributes and defaults 
THEN RESTORE GRAPHICS 
CONTINUE 
END IF 


END HANDLER 
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ROTATE 


When used in a DRAW statement, the ROTATE function rotates points 
specified in a PICTURE subprogram. ROTATE can also be used in the 
MAT statement to create a new matrix. 


Format 


In the DRAW statement 
DRAW _pic-name[(param-list)] WITH ROTATE/(angle) [ * matrix2]... 


In the MAT statement 
MAT matrix! = ROTATE (angle) [ * matrix2]... 


Syntax Rules 


1. Angle can be in radians or degrees, depending on the option you 
specify with the OPTION ANGLE statement. The default is radian 


2. Matrix1 and matrix2 must be two-dimensional numeric arrays that 
zero based with upper bounds of 4 in both directions. VAX BASIC 
signals a compile-time error when the compiler detects a nonzero- 
based matrix; otherwise, a run-time error is signaled. Packed decin 
arrays are invalid. 


3. Matrix2 can also be one of the valid transformation functions from 
DRAW statement, including the following: 


e SCALE 
e SHEAR 
e SHIFT 


¢ TRANSFORM 
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ROTATE can be used only on the right-hand side of a MAT statement 
or as a transformation function in the WITH clause of the DRAW 
statement. 


Like other transformation functions, the ROTATE function affects 
coordinates displayed with PLOT and MAT PLOT statements within 
pictures. Similarly, input points accepted with GET and MAT GET 
statements within a picture are affected by the inverse of a ROTATE 
function specified on the DRAW statement that invokes the picture. 


Points are rotated about the point of origin 0,0. A positive argument 
rotates the point x,y in a counterclockwise direction about the point of 
origin of the world coordinates. A negative value rotates the point in 
a clockwise direction. You can alter the point of origin by setting the 
window such that the point 0,0 is at the center of the window. 


For an example and more information, see the DRAW statement in 
this chapter. 
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When used in the DRAW statement, the SCALE function applies a scal 
factor to the coordinates of points specified in a PICTURE subprogram. 
SCALE can also be used in the MAT statement to create a new matrix. 


Format 


In the DRAW Statement 
DRAW _pic-name[(param-list)] WITH SCALE/(real-exp? [, real-exp2]) [ * matrix2 ]. 


In the MAT Statement 
MAT matrix? = SCALE(real-exp7 [, real-exp2]) [ * matrix2]... 


Syntax Rules 


1. Real-exp1 indicates the scale factor that is applied to the x-coordina 
Real-exp2 indicates the scale factor that is applied to the y-coordina 


3. Matrix1 and matrix2 must be two-dimensional numeric arrays that 
zero-based with upper bounds of 4 in both directions. VAX BASIC 
signals a compile-time error when the compiler detects a nonzero- 
based matrix; otherwise, a run-time error is signaled. Packed decin 
arrays are invalid. 


4. Matrix2 can also be one of the valid transformation functions from 
DRAW statement, including the following: 


e ROTATE 
e SHEAR 
e = SHIFT 


e TRANSFORM 
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SCALE can be used only on the right-hand side of a MAT statement 
or as a transformation function in the WITH clause of the DRAW 
statement. 


When real-exp2 is not included, the scale factor for real-exp1 is applied 
to both the x- and y-coordinates. 

Like other transformation functions, the SCALE function affects 
coordinates displayed with PLOT and MAT PLOT statements within 
pictures. Similarly, input points accepted with GET and MAT GET 
statements within a picture definition are affected by the inverse of a 
SCALE function specified on the DRAW statement that invokes the 
picture. 


For an example and more information, see the DRAW statement in 
this chapter. 
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SET AREA COLOR 


The SET AREA COLOR statement allows you to specify the color of the 
area fill. 


Format 
SET AREA COLOR int-exp 


Syntax Rules 


Int-exp must be a valid color value for the all devices in use, and must be 
greater than zero. 


Remarks 


1. Changing the area color affects the subsequent display of areas on all 
active devices with color capabilities. You cannot specify a particular 
device with this statement. 


2. Changing color values may affect the shading on some black and 
white devices. 


3. The actual colors displayed are device dependent. If you set the color 
to an index value that is undefined for a particular device, results are 
unpredictable. 
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On VT125 and VT240 terminals with the color option, the default 
values for int-exp represent the following colors: 


Index Color 
0 Black 
1 Green 
Zz Red 

3 Blue 


See also the SET COLOR MIX statement for related information. 


PROGRAM samples 


DECLARE LONG CONSTANT green = 1 & 
,red = 2 & 
»blue = 3 


SET LINE COLOR green 

GRAPH LINES 0.05,1; 0.05,0 

SET POINT COLOR blue 

GRAPH POINTS 0.1,0.7; 0.1,0.3 

SET AREA COLOR red 

GRAPH AREA 0.1,0.5; 0.5,0.8; & 
0.35,0.5; 0.5,0.2 

SET TEXT COLOR green 

GRAPH TEXT AT 0.6,0.5 : "Color me simple" 


END PROGRAM 
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Output 


( 
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DET AREA STYLE 


‘ormat 


The SET AREA STYLE statement lets you specify your choice of fill style 
for an area. 


SET AREA STYLE _ str-exp 


iyntax Rules 


lemarks 


The area style value can be one of the following four string values (in 
lower- or uppercase): 


HOLLOW 
SOLID 
PATTERN 
HATCH 


The initial area style value is solid. 

When the area style is hollow, the following two output statements 
produce the same results (a triangle with the outline displayed). 
Example 

SET AREA STYLE "Hollow" 


GRAPH AREA : 0.2,0.2; & 
0.4,0.8; & 
0.6,0.4 

GRAPH LINES : 0.2,0.2; & 
0.4,0.8; & 
0.6,0.4; & 
0.2,0.2 
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3. The pattern and hatch styles both have indices that can be set with 
the SET AREA STYLE INDEX statement. 


OPTION TYPE = EXPLICIT 
EXTERNAL PICTURE sample 

SET AREA STYLE "SOLID" 

DRAW sample 

SET AREA STYLE "HOLLOW" 

DRAW sample WITH SHIFT(0.25,0) 
SET AREA STYLE "PATTERN" 

DRAW sample WITH SHIFT(0.5,0) 
SET AREA STYLE "HATCH" 

DRAW sample WITH SHIFT(0.75,0) 
END 


PICTURE sample 
DECLARE SINGLE x_sample(3), y_sample(3) 


x_sample(0) = 0.0 
x_sample(1) = 0.25 
x_sample(2) = 0.25 
x_sample(3) = 0.0 
y_sample(0) = 1.0 
y_sample(1) = 1.0 
y_sample(2) = 0.0 
y_sample(3) = 0.0 
MAT PLOT AREA x_sample, y_sample 
END PICTURE 
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Output 
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SET AREA STYLE INDEX 


The SET AREA STYLE INDEX statement lets you specify your choice of 
index for hatch or pattern area fill styles. 


Format 
SET AREA STYLE INDEX _int-exp 


Syntax Rules 
None. 
Remarks 


1. The area style index value specifies one of the various hatch or patten 
styles. The initial value for the index is 1. There are no indices for 
hollow or solid area styles. The indices available for VT125 and 
VT240 terminals are listed in Chapter 3. 


2. Values for the AREA STYLE INDEX are device dependent. If you 
set the index to a value that is undefined for a device, results are 
unpredictable. 


OPTION TYPE = EXPLICIT 
DECLARE LONG variety 
EXTERNAL PICTURE sample 
SET AREA STYLE "hatch" 
FOR variety = 1 TO 10 STEP 2 
SET AREA STYLE INDEX variety 
DRAW sample WITH SHIFT (0.1 * variety,0) 
NEXT variety 
END 
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Output 
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SET CHOICE ECHO AREA 


The SET CHOICE ECHO AREA statement lets you specify the boundaries 
of the CHOICE echo area. 


Format 
SET CHOICE ECHO AREA) | *2evid : 
, UNIT int-exp 
real-exp1, real-exp2, real-exp3, real-exp4 
Syntax Rules 
1. Real-exp1, real-exp2, real-exp3, and real-exp4 must be floating-point 
expressions to represent the left, right, bottom, and top boundaries 
respectively. 
2. When specified, dev-id must be the first clause listed and must be 
preceded by the number sign (#). 
3. If one or more optional clauses are included, one colon (:) is required 
before real-exp1. 
Remarks 
1. The echo area is the portion of your screen where the prompt appears 
and where input can be supplied by a user. 
2. The optional dev-id identifies the device for which you want to set the 


echo area. If no identification clause is included, VAX BASIC uses a 
default identification of #0. If an identification clause is included, the 
device specified must have been opened explicitly or opened by VAX 
BASIC as the default device. 
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Boundaries must be specified in device coordinates. To determine 

the possible values on a particular device, use the ASK DEVICE 

SIZE statement. To determine the current boundaries, use the ASK 
CHOICE ECHO AREA statement. Appendix B lists the boundaries for 
VAXstations and VT125 and VT240 terminals. 


The default echo area for CHOICE input is device dependent. The 
default area is in effect until a SET CHOICE ECHO AREA statement 
is executed. 


The optional UNIT clause allows you to specify an alternative means 
of supplying the input. For instance, the position of points can be 
entered with mouse, or with the keyboard arrow keys. Each of these 
methods of data entry is a different unit. The default unit value for 
int-exp for each input type is 1; the default is used throughout this 
manual. For information about the units available on a particular 
device, see the hardware documentation for that device, as well as the 
VAX GKS documentation. 


Be aware that the text height cannot be reduced lower than the 
smallest text height available for the device. Therefore, you should 
ensure that the CHOICE echo area is large enough to list the menu 
items you specify. 

Subsequent requests for CHOICE input use the echo boundaries 
you supply until another SET CHOICE ECHO AREA statement is 
executed. 
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Example 


OPTION TYPE = EXPLICIT 
DECLARE SINGLE left_i,right_1,bottom,top, & 
LONG which_floor 

OPEN "office-term" FOR GRAPHICS AS DEVICE #1 

ASK CHOICE ECHO AREA #1 : left_1,right_1,bottom,top 

I+ 

!Set the echo area to the full screen 

1- 

SET CHOICE ECHO AREA #1 : O 
»right_1i 
»bottom 
, top 

SET INITIAL CHOICE , LIST ("upstairs", 
"downstairs", 
"attic", 
"loft", 
"basement" ) 


Ree 


& & & & & 


od 
LOCATE CHOICE #1 : which_floor 


Output 


A 
aero SEE 


upstairs 
downstairs 
attic 

loft 


basement 


ne ene ee 


2K-5533-86 
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ET CLIP 


The SET CLIP statement lets you change the status of the clipping rectan- 
gle in the world viewport. 


ormat 
SET CLIP = str-exp 


yntax Rules 


Values for str-exp can be equivalent to “ON” or “OFF” (in lower- or 
uppercase). 


iemarks 


1. Clipping is enabled at the start of program execution. 


2. When clipping is enabled with the SET CLIP “ON” statement, graphics 
objects with world coordinate values exceeding the limits of the world 
window are not displayed. 


3. When clipping is disabled with the SET CLIP “OFF” statement, 
graphics objects with world coordinate values that exceed the limits 
of the world window are displayed providing that the points are also 
within the device window. 


4. When clipping is enabled, STRING precision clips a text string at the 
world viewport boundary. No text string starts beyond the world 
viewport boundary. 


5. When clipping is enabled, CHAR precision clips a text string by 
character at the world viewport. No character extends beyond the 
world viewport boundary. Some devices display part of a character 
that spans the world viewport boundary. 
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6. When clipping is enabled, STROKE precision clips text precisely at thi 
world viewport boundary. For example, if only half a character falls 
inside the world viewport boundary, only this half is displayed on th 
screen. 


7. The SET CLIP statement is invalid within a picture. 
Example 


PROGRAM demo_clip 
EXTERNAL PICTURE BASIC_people 
SET WINDOW 0,1,0,0.74 
SET VIEWPORT 0,1,0,0.74 
Screen1: 
SET CLIP "Off" 
DRAW BASIC_people 
SET TEXT FONT -1, "CHAR" 
GRAPH TEXT AT 0,0.1 : "Clipping is OFF" 
SLEEP 47% 
CLEAR 
Screen2: 
SET CLIP "On" 
DRAW BASIC_people 
SET TEXT FONT -1, "CHAR" 
GRAPH TEXT AT 0,0.1 : "Clipping is ON" 
END PROGRAM 


PICTURE BASIC_people 
EXTERNAL PICTURE circle 
DRAW circle WITH SCALE(0.125,0.125) * SHIFT(0.235,0.6) 
GRAPH AREA 0.3,0.6; 0.5,0.3; 0.1,0.3 
SET TEXT FONT -8, "STROKE" 
SET TEXT HEIGHT 0.05 
GRAPH TEXT AT 0.2,0.95 :"Your" 
GRAPH TEXT AT 0.185,0.85 :"BASIC" 
GRAPH TEXT AT 0.195,0.75 : "woman" 
DRAW circle WITH SCALE(0.125,0.125) * SHIFT(0.675,0.6) 
GRAPH AREA 0.55,0.6; 0.95,0.6; 0.75,0.3 


GRAPH TEXT AT 0.655,0.95 :"Your" 

GRAPH TEXT AT 0.628,0.85 :"BASIC" 

GRAPH TEXT AT 0.665,0.75 :"man" 
END PICTURE 
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PICTURE circle 
OPTION TYPE = EXPLICIT 
DECLARE SINGLE- CONSTANT radius = 0.5 
DECLARE LONG CONSTANT npoints = 40 
DECLARE SINGLE angle,increment ,x,y 
DIM SINGLE xs(npoints), ys(npoints) 
increment = 2*pi/npoints 
angle = 0 
FOR loop_count = 0 TO npoints - 1 
x = COS( angle ) * radius + 0.5 
y = SIN( angle ) * radius + 0.5 
xs(loop_count) = x 
ys(loop_count) 
angle = angle + increment 
NEXT loop_count 
xs(npoints) = xs(0) 
ys(npoints) = ys(0) 
MAT PLOT LINES xs, ys 
END PICTURE 


Output Screen 1: 


{ Your Your \ 


BASIC BASIC 


WOTTLATL TYIVLATL 


AV 


Clipping is OFF 


ee 


2K-5519-86 
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Output Screen 2: 


f | \ 


AV 


Clipping is ON 


ee eee eee ne 


ZK-5520-86 
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ET COLOR MIX 


ormat 


The SET COLOR MIX statement allows you to specify the intensities for 
red, green, and blue for a particular color index. 


SET COLOR MIX = [ #dev-id ] , INDEX int-exp : real-exp1, real-exp2, real-exp3 


yntax Rules 


emarks 


Ne 


Sa ey 


The optional dev-id must be preceded by a number sign (#) . 


You specify the color index with int-exp, which must be greater than 
zero. 


Real-exp1 sets the value associated with red. 
Real-exp2 sets the value associated with green. 
Real-exp3 sets the value associated with blue. 


Values for the intensities of the colors red, green, and blue must be 
greater than or equal to 0.0 and less than or equal to 1.0. 


The optional dev-id identifies the device for which you want to set the 
color mix. If no identification clause is included, VAX BASIC uses a 
default identification of #0. If an identification clause is included, the 
device specified must have been opened explicitly, or opened by VAX 
BASIC as the default device. 
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2. The default intensity values for color indices 1, 2, and 3 are as follow 


Color Red 
Index Color Intensity 
0 Black 0.0 

1 Green 0.0 

2 Red 1.0 

3 Blue 0.0 


Green Blue 
Intensity Intensity 
0.0 0.0 

1.0 0.0 

0.0 0.0 

0.0 1.0 


3. When you specify the intensities for red, green, and blue, you mix 
the colors for the index value. The color mix is dependent on the 
intensities you specify, not on the value of the index. For instance, tl 
following three statements set the indices 1, 2, and 3, to be the same 


color: 


SET COLOR MIX ,INDEX 1 : 0.4281, 0.7119, 0.7119 
SET COLOR MIX ,INDEX 2 : 0.4281, 0.7119, 0.7119 
SET COLOR MIX , INDEX 3 : 0.4281, 0.7119, 0.7119 


4. Ifa device does not support the requested intensity, it will approxi- 


mate the requested color. 


5. Possible color intensities for red, green, and blue on VAXstations anc 
on VT125 and VT240 terminals are listed in Appendix B. 


DECLARE LONG growing, loop 
SET WINDOW 0,120,0,120 
FOR growing = 1 TO 10 
SET LINE SIZE growing 
SELECT growing 
CASE = 1,3,5,7,9 
SET COLOR MIX , INDEX 1 
SET LINE COLOR 1 
CASE = 2,4,6,8,10 


SET COLOR MIX , INDEX 2 : 


SET LINE COLOR 2 
END SELECT 
GRAPH LINES growing~2,120; growing“2,0 
NEXT growing 
END 
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: 1, 0.1400, 1 


1, 1, 0.4200 


SET COLOR MIX 


Output 
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The SET DEVICE VIEWPORT statement lets you change the boundaries 
of the device viewport. 


Format 


SET DEVICE VIEWPORT [ #dev-id: ] real-exp1, real-exp2, real-exp3, real-exp4 
Syntax Rules 


1. Real-exp1, real-exp2, real-exp3, and real-exp4 must be floating-point 
expressions to represent the left, right, bottom, and top boundaries 
respectively. 


2. The optional dev-id must be preceded by a number sign (#) and 
followed by a colon (:). 


Remarks 


1. The device viewport is the portion of the device selected for a graphic 
display. 

2. The optional dev-id identifies the device for which you want to set th 
viewport. If no identification clause is included, VAX BASIC uses a 
default identification of #0. If an identification clause is included, the 
device specified must have been opened explicitly, or opened by VA 
BASIC as the default device. 


3. The default device viewport is device dependent; however, it is usuall 
the largest square region the device can accommodate. 


4. If the device viewport is not already clear, the SET DEVICE 
VIEWPORT statement clears the display surface. 
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5. When the device window and device viewport do not match in 
shape, VAX BASIC uses the largest possible device viewport that 
matches the shape of the device window. For instance, if you select a 
long thin device window and a square device viewport, VAX BASIC 
overrides your selection of a device viewport and uses the largest 
device viewport possible that is also long and thin, thus matching the 
device window as closely as possible. 


6. Boundaries must be supplied as device coordinates. To determine the 
device coordinates for a particular device, use the ASK DEVICE SIZE 
statement. 


7. You cannot change the clipping status at the device viewport bound- 
aries. If an object is not within the device window, it is not displayed 
in the device viewport. 


8. A SET DEVICE VIEWPORT statement is invalid in a picture definition. 


OPTION TYPE = EXPLICIT 
DECLARE SINGLE left_1,right_1,bottom,top 
EXTERNAL PICTURE swan 
'+ 
!Set the world window - one swan fills entire NDC space 
!- 
SET WINDOW 0,100,0,100 
Screen1: 
DRAW swan 
SLEEP 5% 
CLEAR 
ASK DEVICE VIEWPORT left_1,right_1,bottom,top 
1+ 
!'Set the device window to half of NDC space 
t- 
SET DEVICE WINDOW 0,0.5,0,1 
I+ 
!Set the device viewport to the left half of the default 
- 
SET DEVICE VIEWPORT left_1,right_1/2, bottom, top 
Screen2: 
'+ 
!After device transformation, only part of swan displayed 
- 
DRAW swan 
END 
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Output Screen 1: 





ZK-4953-86 


Output Screen 2: 





ZK -4965-86 
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SET DEVICE WINDOW 


-ormat 


The SET DEVICE WINDOW statement lets you change the boundaries of 
the device window. 


SET DEVICE WINDOW [| #dev-id: ] real-exp1, real-exp2, real-exp3, real-exp4 


byntax Rules 


femarks 


Real-exp1, real-exp2, real-exp3, and real-exp4 must be floating-point 
expressions to represent the left, right, bottom, and top boundaries 
respectively. Values must be within the range 0.0 to 1.0. 


The optional dev-id must be preceded by a number sign (#) and 
followed by a colon (:). 


The device window is a portion of NDC space you select to be 
displayed on the device viewport of an active device. 


The default device window is the entire NDC space with boundaries 
of 0,1,0,1. 


The optional dev-id identifies the device for which you want to set 
the window. If no identification clause is included, VAX BASIC uses a 
default identification of #0. If an identification clause is included, the 
device specified must have been opened explicitly, or opened by VAX 
BASIC as the default device. 


The boundaries you set must be within the range 0.0 to 1.0. 


When the device window and device viewport do not match in 
shape, VAX BASIC uses the largest possible device viewport that 
matches the shape of the device window. For instance, if you select a 
long thin device window and a square device viewport, VAX BASIC 
overrides your selection of a device viewport and uses the largest 
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Example 


device viewport possible that is also long and thin, thus matching the 
device window as closely as possible. 


6. Clipping of graphics objects outside the device window cannot be 
disabled. If an object is not within the device window, it is not 
displayed in the device viewport. 


7. The SET DEVICE WINDOW statement clears the display surface if it 
is not already cleared. 


8. A SET DEVICE WINDOW statement is invalid in a picture definition. 


OPTION TYPE = EXPLICIT 
DECLARE SINGLE left_1,right_1,bottom,top 
EXTERNAL PICTURE swan 
+ 
!Set world window so that swan fills NDC space 
{- 
SET WINDOW , TRAN 1 : 0,100,0,100 
Screen1: 
DRAW swan 
SLEEP 5% 
CLEAR 
1+ 
'Select entire NDC space for world viewport 
t- 
SET VIEWPORT , TRAN 1 : 0,1,0,1 
I+ 
!Select the top right square of NDC space as the device window 
!but leave device viewport as default 
{- 
SET DEVICE WINDOW 0.5,1,0.5,1 
Screen2: 
DRAW swan 
END 
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Output Screen 1: 





ZK-4953:86 


Output Screen 2: 


ZK-4959-86 
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SET INITIAL CHOICE 


The SET INITIAL CHOICE statement allows you to specify items to be 
displayed in a menu as well as set up an initial selection for the user. 


Format 
#dev-id 
, UNIT int-exp7 
SET INITIAL CHOICE , COUNT int-exp2 . int-exp3 
Str-array 
7 LIST { (str-exp [ , str-exp J...) } 
Syntax Rules 


1. Int-exp3 specifies the number of the menu item for the initial choice. 


2. When specified, dev-id must be the first clause listed and must be 
preceded by the number sign (#). 


3. The optional LIST, COUNT, and UNIT clauses can be specified in any 
order. 


4. If one or more optional clauses are included, one colon (:) is required 
before int-exp3. 


5. Str-array must be a one-dimensional array containing string data types 
Virtual arrays are invalid. 


6. Int-exp2 cannot be greater than the number of elements in str-array. 
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The optional dev-id identifies the device for which you want to set 
up a menu. If no identification clause is included, VAX BASIC uses a 
default identification of #0. If an identification clause is included, the 
device specified must have been opened explicitly, or opened by VAX 
BASIC as the default device. 


The LIST clause specifies strings to be displayed in a menu. You can 
include a list of string expressions enclosed in parentheses, or an array 
containing the strings. When an array is included, specify only the 
array name; do not include parentheses to indicate the whole array. 

If no LIST clause is included, the default menu is displayed unless 

an alternative has been set with a previous SET INITIAL CHOICE 
statement. 


The COUNT clause specifies the number of items in the string array 
to be displayed in the menu, starting with the lowest element in the 
array. If no string array is specified in the LIST clause, the COUNT 
clause is not valid and a compile-time error message is issued. The 
user cannot move the cursor to an item that is not displayed. If no 
COUNT clause is included, all of the menu items in the array elements 
are displayed. 


The initial choice specified in a LOCATE CHOICE statement overrides 
the initial choice specified in a SET INITIAL CHOICE statement. 


The optional UNIT clause allows you to specify an alternative means 
of supplying the input. For instance, the position of points can be 
entered with a mouse, or with the keyboard arrow keys. Each of these 
methods of data entry is a different unit. The default unit value for 
int-exp for each input type is 1; the default is used throughout this 
manual. For information about the units available on a particular 
device, see the hardware documentation for that device, as well as the 
VAX GKS documentation. 


Subsequent requests for CHOICE input use the items specified until 
another SET INITIAL CHOICE statement sets an alternative menu. 
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In the following example an array of 10 strings is supplied to the SET 
INITIAL CHOICE statement. The COUNT clause specifies that only the 
first five array elements (up to menu—items(4)) are to be displayed. The 
user cannot select a language that is not among the first five listed. 


OPTION TYPE = EXPLICIT 
DECLARE LONG language 
DIM STRING menu_items (9) 


menu_items(0) = "BASIC" 

menu_items(1) = "Pascal" 

menu_items(2) = "Cc" 

menu_items(3) = "COBOL" 

menu_items(4) = "FORTRAN" 

menu_items(5) = "LISP" 

menu_items(6) = "PL/1" 

menu_items(7) = "SCAN" 

menu_items(8) = "RPG/II" 

menu_items(9) = "LOGO" 

SET INITIAL CHOICE , COUNT 5 & 
» LIST menu_items & 


21 
LOCATE CHOICE language 
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Output 







qasca 
G 
COBOL 
FORTRAN 





Ie 
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SET INITIAL MULTIPOINT 


The SET INITIAL MULTIPOINT statement allows you to specify a set of 
initial points that a user can accept as the default input. 


Format 


# dev-id 


SET INITIAL MULTIPOINT =| + UNIT int-exp/ 


Syntax Rules 


, COUNT int-exp2 
, USING TRAN int-exp3 


x-array, y-array 


When specified, dev-id must be the first clause listed and must be 
preceded by the number sign (#). 


The optional UNIT, COUNT, and USING TRAN clauses can be in an 
order. 


Int-exp3 must be an integer between 1 and 255. 


If one or more optional clauses are included, one colon (:) is requirec 
before x-array. 


For MULTIPOINT, specify only the array name; do not use parenthe- 
ses to indicate the whole array. 


X-array and y_array must be one-dimensional arrays that contain onl 
integer or real data types. Virtual arrays are not valid. 


Int-exp2 cannot be greater than the number of elements in the coordi 
nate arrays. 
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emarks 


SET INITIAL MULTIPOINT 


The optional dev-id identifies the device for which you want to set 
up the initial display. If no identification clause is included, VAX 
BASIC uses a default identification of #0. If an identification clause 
is included, the device specified must have been opened explicitly, or 
opened by VAX BASIC as the default device. 


The COUNT clause allows you to display a selected number of points 
from the arrays starting with the first elements. If the COUNT clause 
is not specified, all of the points specified in the arrays are displayed. 


Depending on the device, a user can delete the initial points with the 
DELETE key. 


The USING TRAN clause allows you to specify an alternative trans- 
formation to be used to interpret the world coordinates of the initial 
points you specify. If no USING TRAN clause is included, the initial 
points are displayed using the currently established transformation. 


Subsequent calls for MULTIPOINT input use the points specified until 
another SET INITIAL MULTIPOINT statement is executed or until 
the initial point is overridden by an AT clause in a MAT LOCATE 
POINTS or MAT GET POINTS statement. 


If you do not include a SET INITIAL MULTIPOINT statement, VAX 
BASIC uses the initial point specified in a MAT LOCATE POINTS or 
MAT GET POINTS statement. 


The optional UNIT clause allows you to specify an alternative means 
of supplying the input. For instance, the position of points can be 
entered with a mouse, or with the keyboard arrow keys. Each of these 
methods of data entry is a different unit. The default unit value for 
int-exp for each input type is 1; the default is used throughout this 
manual. For information about the units available on a particular 
device, see the hardware documentation for that device, as well as the 
VAX GKS documentation. 


Execution of a MAT LOCATE POINTS or MAT GET POINTS state- 
ment causes the display of the initial points. 


VAX BASIC Graphics Statements 9-175 


SET INITIAL MULTIPOINT 





Example 


OPTION TYPE = EXPLICIT 
DECLARE LONG CONSTANT max_points = 13 
DECLARE LONG loop, how_many 
DIM SINGLE maze_x(8), maze_y(8), & 
SINGLE input_xs(1 TO max_points), input_ys(1i TO max_points) 
SET WINDOW , TRAN 1 : 0,100,0,100 


DATA 0.1,0.8, 0.2,0.7, 0.3,0.8, 0.3,0.6, & 
0.3,0.4, 0.2,0.5, 0.2,0.4, 0.1,0.4, & 
0.1,0.2 

READ maze_x(loop), maze_y(loop) FOR loop = O TO 8 

SET INITIAL MULTIPOINT , COUNT 5 & 


>: maze_x, maze_y 
MAT LOCATE POINTS , COUNT how_many : input_xs, input_ys 
IF how_many > max_points 

THEN how_many = max_points 
END IF 
SET POINT COLOR 2 
MAT GRAPH POINTS , COUNT how_many : input_xs, input_ys 
END 


Output 


The output shows only the initial points presented to the user. 


(ES 


Oa 
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ET INITIAL POINT 


The SET INITIAL POINT statement allows you to specify an initial point 
that a user can enter as the default input. 


prmat 


# dev-id 


SET INITIAL POINT _ UNIT int-exp7 x-coord, y-coord 


yntax Rules 


emarks 


, USING TRAN int-exp2 


When specified, dev-id must be the first clause listed and must be 
preceded by the number sign (#). 


The optional UNIT and USING TRAN clauses can be in any order. 


If one or more optional clauses are included, one colon (:) is required 
before x-coord. 


Int-exp2 must be an integer between 1 and 255. 


The optional dev-id identifies the device for which you want to set the 
initial point. If no identification clause is included, VAX BASIC uses a 
default identification of #0. If an identification clause is included, the 
device specified must have been opened explicitly or opened by VAX 
BASIC as the default device. 


The USING TRAN clause allows you to specify a transformation to 
interpret the world coordinates of the initial point you specify. If no 
USING TRAN clause is included, the initial point is displayed using 
the currently established transformation. 
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3. Subsequent calls for POINT input use the initial point specified until 
another initial point is set by a SET INITIAL POINT statement or a 
LOCATE/GET POINT statement. 


4. The optional UNIT clause allows you to specify an alternative means 
of supplying the input. For instance, the position of points can be 
entered with a mouse, or with the keyboard arrow keys. Each of the: 
methods of data entry is a different unit. The default unit value for 
int-exp for each input type is 1; the default is used throughout this 
manual. For information about the units available on a particular 
device, see the hardware documentation for that device, as well as tt 
VAX GKS documentation. 


OPTION TYPE = EXPLICIT 

DECLARE SINGLE center_x, center_y, radius 

DECLARE LONG which_tran 

SET WINDOW , TRAN 1 : 0,100,0,100 

SET WINDOW , TRAN 2 : 10,40,0,5 

SET TRANSFORMATION 1 

SET INITIAL POINT , USING TRAN 2 & 
: 20,3.5 

LOCATE POINT center_x, center_y , which_tran 

LOCATE VALUE , RANGE 0.1 TO 0.4 : radius 


END 
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VET INITIAL STRING 


The SET INITIAL STRING statement allows you to specify an initial string 
expression that is presented to a user when string input is requested. A 
user can enter the initial string or enter another string. 


ormat 


SET INITIAL STRING #dev-id ; str-exp 


iyntax Rules 


lemarks 


_ UNIT int-exp 


When specified, dev-id must be the first clause listed and must be 
preceded by the number sign (#). 


If one or more optional clauses are included, one colon (:) is required 
before str-exp. 


The optional dev-id identifies the device for which you want to set the 
initial string. If no identification clause is included, VAX BASIC uses a 
default identification of #0. If an identification clause is included, the 

device specified must have been opened explicitly, or opened by VAX 

BASIC as the default device. 


Subsequent requests for STRING input use the item specified until an- 
other SET INITIAL STRING statement or LOCATE STRING statement 
specifies an alternative. 
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3. VAX BASIC appends the user-supplied string to the initial string you 
supply in a SET INITIAL STRING or a LOCATE STRING statement. 
If the user accepts the initial string with a null response, str-var 
contains only the initial string. Depending on the device, a user may 
be able to delete the initial string by pressing CTRL/U or using the 
DELETE key. 


4. The optional UNIT clause allows you to specify an alternative means 
of supplying the input. For instance, the position of points can be 
entered with a mouse or with the keyboard arrow keys. Each of thes« 
methods of data entry is a different unit. The default unit value for 
int-exp for each input type is 1; the default is used throughout this 
manual. For information about the units available on a particular 
device, see the hardware documentation for that device, as well as th 
VAX GKS documentation. 


Example 


PROGRAM select_an_item 
DECLARE STRING CONSTANT init_string = & 
"YES or NO [yes]>" 
DECLARE STRING user_string 
EXTERNAL PICTURE Main_menu, Input_menu 
OPEN "my_term" FOR GRAPHICS AS DEVICE #1 


SET INITIAL STRING #1 : init_string 
LOCATE STRING #1 : user_string 
IF init_string = user_string 
THEN 
DRAW Main_menu 
ELSE 
DRAW Input_menu 
END IF 
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Output 


OS 


YES or NO [yes]: 
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SET INITIAL VALUE 


The SET INITIAL VALUE statement allows you to specify an initial 
floating-point number within a specified range. A user can enter this 
value or an alternative. 


Format 
#dev-id 
SET INITIAL VALUE , UNIT int-exp real-exp3 
, RANGE real-exp7 TO real-exp2 
Syntax Rules 


1. When specified, dev-id must be the first clause listed and must be 
preceded by the number sign (#). 


The optional UNIT and RANGE clauses can be in any order. 
3. Real-exp1 must be less than real-exp2 in the optional RANGE clause. 


4. If one or more optional clauses are included, one colon (:) is required 
before real-exp3. 


5. You specify the initial value in real-exp3. 
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Remarks 


SET INITIAL VALUE 


The optional dev-id identifies the device for which you want to set an 
initial value. If no identification clause is included, VAX BASIC uses a 
default identification of #0. If an identification clause is included, the 
device specified must have been opened explicitly or opened by VAX 
BASIC as the default device. 


Subsequent requests for value input with the LOCATE VALUE state- 
ment use the initial value and range specified until another INITIAL 
VALUE or LOCATE VALUE statement specifies another value. 


The RANGE clause specifies the lowest and highest acceptable input. 
The user-supplied value and the initial value must be within this 
range. VAX BASIC signals the run-time error ILLINIVAL, “Illegal 
initial value” (ERR = 284), when the initial value is not within the 
specified range. 

When the LOCATE VALUE statement is executed, the user has the 
option of entering the initial value specified in this statement or 
another value as input. 


The optional UNIT clause allows you to specify an alternative means 
of supplying the input. For instance, the position of points can be 
entered with a mouse, or with the keyboard arrow keys. Each of these 
methods of data entry is a different unit. The default unit value for 
int-exp for each input type is 1; the default is used throughout this 
manual. For information about the units available on a particular 
device, see the hardware documentation for that device, as well as the 
VAX GKS documentation. 
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Example 





OPTION TYPE = EXPLICIT 

EXTERNAL SUB Graphics_display (SINGLE) 
DECLARE SINGLE which_val 

OPEN "VT124" FOR GRAPHICS AS DEVICE #1 


Input_rtn: 
SET INITIAL VALUE #1 
» RANGE 1 TO 30 
>: 15 
LOCATE VALUE #1 : which_val 
IF which_val =< 15 
THEN GOTO Large_size 
ELSE CALL Graphics_display(which_val) 
END IF 


Output 
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ET INPUT PRIORITY 


The SET INPUT PRIORITY statement allows you to modify the transfor- 
mation priority list. 


ormat 


int-var1 < eee } 
SETINPUT PRR eee ee 2 


yntax Rules 


The constant or variable values must be between 1 and 255. Expressions 
are not allowed. 


emarks 


1. When points are input from a device, VAX BASIC maps these points to 
world coordinates according to the specifications for the transformation 
that the point or points fall in. 


When more than one transformation is defined, world viewports can 
overlap. The viewport with the highest priority that contains all of the 
points is used to map the points back to world coordinates. For more 
information, see Chapter 7. 


2. Initially, the transformation with the highest priority is transformation 
1. Transformation 1 is always defined and initially includes the entire 
NDC space. 


3. When other transformations are defined, the highest input priority 
is the transformation that has been most recently established with 
a SET INPUT PRIORITY, SET WINDOW, SET VIEWPORT, or SET 
TRANSFORMATION statement. 
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4. The less-than sign (<) sets the first value to be a lower priority than 
the second. The greater-than sign (>) sets the first value to be a 
higher priority than the second. 


5. Changing the input priority does not change the transformation 
currently in effect for displaying output. 


6. When transformation 1 has been redefined with a viewport other 
than 0,1,0,1, a point can be input beyond the limits of any defined 
viewport. When this happens, VAX BASIC signals an error. 


7. A SET INPUT PRIORITY statement is invalid within a picture defini- 
tion. 


DECLARE LONG how_many,counter 

DIM LONG xforms(10) 

SET WINDOW ,TRAN 1: 1000,2000,0,100 
SET VIEWPORT ,TRAN 1 : 0,1,0,1 

SET WINDOW , TRAN 2 : 0,100,0,100 


SET VIEWPORT ,TRAN 2 : 0,1,0,0,0.5 
SET WINDOW , TRAN 3 : -1,1,-1,1 
SET VIEWPORT , TRAN 3 : 0.5,1,0.5,1 


1+ 

!'Show tran priority list 

1- 

ASK TRANSFORMATION LIST , COUNT how_many : xforms 
PRINT xforms(counter) FOR counter = 0 TO (how_many - 1) 
\+ 

'Set highest priority to TRAN 2 for input 

!- 

SET INPUT PRIORITY 2 > 3 

I+ 

!Show new priority list 

'- 

ASK TRANSFORMATION LIST , COUNT how_many : xforms 
PRINT xforms(counter) FOR counter = 0 TO (how_many - 1) 
END 


Output 


mw Ww 


mm WD 
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SET LINE COLOR 


The SET LINE COLOR statement allows you to specify a color for lines. 


ormat 


SET LINE COLOR = int-exp 


yntax Rules 


Int-exp must be a valid color value for all active devices, and must be 
greater than zero. 


emarks 


1. Changing the line color affects the display of lines on all active 
devices. You cannot specify a particular device with this statement. 


2. Changing color values may affect the shading on some black and 
white devices. 


3. The actual colors displayed are device dependent. If you set the color 
to an index value that is undefined for a particular device, results are 
unpredictable. 


4. On VT125 and VT240 terminals with the color option, the default 
values for int-exp represent the following colors: 


Index 
0 


1 
2 
3 


Color 
Black 
Green 
Red 
Blue 


5. See also the SET COLOR MIX statement for related information. 
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PICTURE line_display (LONG color_var) 

DECLARE SINGLE loop 

SET LINE COLOR color_var 

SET LINE SIZE 3 

PLOT LINES 0.05,loop; 0.95,loop FOR loop = 0.1 TO 1 STEP 0.1 
END PICTURE 


PROGRAM Show_lines 
OPTION ANGLE = DEGREES 
EXTERNAL PICTURE line_display (LONG) 
SET WINDOW -1,1,-1,1 
DRAW line_display(1) 
DRAW line_display(2) WITH ROTATE(90) 
DRAW line_display(1) WITH ROTATE(180) 
DRAW line_display(2) WITH ROTATE(270) 
END PROGRAM 


Output 
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SET LINE SIZE 


The SET LINE SIZE statement allows you to select the current width of 
line. 


Format 


SET LINE SIZE num-exp 
Syntax Rules 
Num-exp must be greater than zero. 
Remarks 


1. Num-exp is the scale factor that is multiplied by the smallest possible 
width of a line. 


2. Subsequent line output is drawn with the size you set until another 
SET LINE SIZE statement is executed. 


3. The default size for the line width is 1. This is the minimum size a 
device can produce. 


4. The range and number of possible line widths are device dependent. 
To determine the maximum size for a particular device, use the ASK 
MAX LINE SIZE statement. If you set the size to a value that is 
undefined for the device, results are unpredictable. 
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Example 


DECLARE LONG growing, loop 
SET WINDOW 0,120,0,120 
FOR growing = 1 TO 10 
SET LINE SIZE growing 
GRAPH LINES growing*2,120; growing~2,0 
NEXT growing 
END 


Output 


Cwltttrpro....) 





nt 
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SET LINE STYLE 


The SET LINE STYLE statement lets you specify the style with which lines 
are drawn. 


Format 


SET LINE STYLE = int-exp 
syntax Rules 
None. 
temarks 


1. The numeric values for line styles represent the following styles: 


Value Line Style 


1 ~—s Solid (default) ssi 
Z Dashed 

3 Dotted 

4 


Dashed-dotted 


Line styles greater than 4 are device dependent. If you set the style to 
a value that is not supported by the device, results are unpredictable. 


2. The default line style is 1, solid. 


3. Subsequent line output is displayed with the style you set until 
another SET LINE STYLE statement is executed. 
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Example 


PROGRAM Demo 

OPTION TYPE = EXPLICIT 

EXTERNAL PICTURE line_demo(LONG) 

DECLARE LONG line_style 

DRAW line_demo(Line_style) FOR line_style = 1 TO 4 
END PROGRAM 


PICTURE line_demo(LONG line style) 
SET LINE STYLE line_style 
GRAPH LINES 0,line_style/5; 1,line_style/5 
GRAPH LINES 0, (line_style/5) + 0.025; 1,(line_style/5) + 0.025 
GRAPH LINES 0, (line_style/5) + 0.055 1,(line_style/5) + 0.05 
GRAPH LINES 0, (line_style/5) + 0.075; 1,(line_style/5) + 0.075 
GRAPH LINES 0, (line_style/5) + 0.1; 1,(line_style/5) + 0.1 

END PICTURE 


Output 
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SET POINT COLOR 


The SET POINT COLOR statement allows you to specify the color for 
points. 


Format 


SET POINT COLOR  int-exp 
Syntax Rules 


Int-exp must be a valid color value for all devices in use, and must be 
greater than zero. 


Remarks 


1. Changing color attributes affects the display of graphics objects on 
all active devices. You cannot specify a particular device with this 
statement. 


2. Changing color values may affect the shading on some black and 
white devices. 


3. The actual colors displayed are device dependent. If you set the color 
to an index value that is undefined for a particular device, results are 
unpredictable. 
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On VT125 and VT240 terminals with the color option, the default 
values for int-exp represent the following colors: 


Index Color 

0 Blak 
1 Green 

2 Red 

3 Blue 


See also the SET COLOR MIX statement for related information. 


PROGRAM bubbles 


OPTION TYPE = EXPLICIT 

EXTERNAL PICTURE markers (LONG, LONG) 

DECLARE LONG CONSTANT blue = 3, pink = 2 

DRAW markers (blue, 4) 

SLEEP 4% 

CLEAR 

SET COLOR MIX , INDEX pink : 0.6258, 0.2142, 0.2142 
DRAW markers (pink, 4) 


END PROGRAM 


PICTURE markers(LONG color_var, LONG style_var) 


SET POINT COLOR color_var 

SET POINT STYLE style_var 

SET POINT SIZE 2 

PLOT POINTS 0.1,0.9; 0.4,0.7; 0.9,0.85; 0.65,0.45 
SET POINT SIZE 1 

PLOT POINTS 0.5,0.8; 0.6,0.9; 0.1,0.7 

SET POINT SIZE 5 

PLOT POINTS 0.8,0.6; 0.3,0.75; 0.7,0.8; 0.725,0.45 
SET POINT SIZE 3 

PLOT POINTS 0.15,0.7; 0.74,0.6; 0.7,0.7; 0.275,0.6 
SET POINT SIZE 1 

PLOT POINTS 0.23,0.35; 0.4,0.4; .67,0.475 


END PICTURE 
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Output 
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SET POINT SIZE 


The SET POINT SIZE statements allow you to select the current size of a 
point. 


Format 


SET POINT SIZE num-exp 
Syntax Rules 
Num-exp must be greater than zero. 


Remarks 


1. Num-exp is the scale factor that is multiplied by the smallest possible 
size of a point. 


2. Subsequent point output is drawn with the size you set until another 
SET POINT SIZE statement is executed. 


3. The default size for points is 1. This is the minimum size a device can 
produce. 


4. Regardless of what size you set for a point size, points set to the dot 
marker are always drawn in the smallest possible size. 


5. The range and number of possible point sizes are device dependent. 
To determine the maximum size for a particular device, use the ASK 
MAX POINT SIZE statements. If you set the size to a value that is 
undefined for the device, results are unpredictable. 
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SET POINT SIZE 
Example 


DECLARE LONG loop 
SET WINDOW 0,10,0,10 
FOR loop = 1 TO 9 
SET POINT SIZE loop 
GRAPH POINTS 5,(10 - loop) 
NEXT loop 
END 


Output 


(SN 


a ea 
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SET POINT STYLE 


The SET POINT STYLE statement lets you specify your choice of style for 
the marker for a point. 


Format 


SET POINT STYLE = int-exp 


Syntax Rules 
None. 


Remarks 


1. The numeric values for point styles represent the following markers: 


Value 
1 


Oo -& W N 


Point Style 

Dot 

Plus sign 
Asterisk (default) 
Circle 


Diagonal cross 


Values greater than 5 are device dependent. If you set the style to a 
value that is not supported by the device, results are unpredictable. 


2. The default point style is 3, an asterisk. 


3. Subsequent points are displayed with the style you set until another 
SET POINT STYLE statement is executed. 
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Example 


SET POINT STYLE 


PROGRAM Demo 

OPTION TYPE = EXPLICIT 

DECLARE LONG point_style 

FOR point_style = 1 TO 5 
SET POINT STYLE point_style 
GRAPH POINTS point_style/10,0.8 

NEXT point_style 

END PROGRAM 


Output 


f 


ae: ae > OS 


ee eee 
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SET STRING ECHO AREA 


The SET STRING ECHO AREA statement lets you specify the boundaries 
of the STRING echo area. 


Format 
SET STRING ECHO AREA | *“ev-id . 
, UNIT int-exp 
real-exp1, real-exp2, real-exp3, real-exp4 
Syntax Rules 
1. Real-exp1, real-exp2, real-exp3, and real-exp4 must be floating-point 
expressions to represent the left, right, bottom, and top boundaries 
respectively. 
2. When specified, dev-id must be the first clause listed and must be 
preceded by the number sign (#). 
3. If one or more optional clauses are included, one colon (:) is required 
before real-exp1. 
Remarks 
1. The echo area is the portion of your screen where the prompt appears 
and where input can be supplied by a user. 
2. The optional dev-id identifies the device for which you want to set the 


echo area. If no identification clause is included, VAX BASIC uses a 
default identification of #0. If an identification clause is included, the 
device specified must have been opened explicitly or opened by VAX 
BASIC as the default device. 
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Boundaries must be specified in device coordinates. To determine 
the possible values on a particular device, use the ASK DEVICE 
SIZE statement. To determine the current boundaries, use the ASK 
STRING ECHO AREA statement. Appendix B lists the boundaries for 
VAXstations and VT125 and VT240 terminals. 


The default echo area for STRING input is device dependent. The 
default area is in effect until a SET STRING ECHO AREA statement is 
executed. 


Subsequent requests for each input type use the echo boundaries you 
supply until another SET STRING ECHO AREA statement is executed. 


Be aware that the text height cannot be reduced lower than the small- 
est text height available for the device. Therefore, you should ensure 
that the STRING echo area is large enough for the text characters you 
specify. 


The optional UNIT clause allows you to specify an alternative means 
of supplying the input. For instance, the position of points can be 
entered with a mouse, or with the keyboard arrow keys. Each of these 
methods of data entry is a different unit. The default unit value for 
int-exp for each input type is 1; the default is used throughout this 
manual. For information about the units available on a particular 
device, see the hardware documentation for that device, as well as the 
VAX GKS documentation. 
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OPTION TYPE = EXPLICIT 

DECLARE SINGLE left_1,right_i,bottom,top 
DECLARE STRING user_string 

OPEN "office-term" FOR GRAPHICS AS DEVICE #1 


ASK STRING ECHO AREA #1 : left_1,right_1,bottom,top 

t+ 

'Set the new echo area 

t- 

SET STRING ECHO AREA #1 : left_1 & 
»right_1 & 
,botton & 
,top * 4 

SET INITIAL STRING #1 : "Enter the answer here>" 

LOCATE STRING #1 : user_string 


Output 


(SN 


Enter the answer here> 





Ia a ee 
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SET TEXT ANGLE 


The SET TEXT ANGLE statement lets you change the angle with which a 
text string is rotated. 


-ormat 


SET TEXT ANGLE = real-exp 
syntax Rules 


Real-exp must be an angle in radians or degrees, as specified in an 
OPTION ANGLE statement; the default is radians. 


Remarks 


1. The default text angle is zero. Characters drawn with the default text 
angle are drawn horizontally across the screen. 


2. Text is rotated about the starting point indicated in the GRAPH TEXT 
statement. 


3. When you set the angle to a positive value, the text is rotated in a 
counterclockwise direction; supplying negative values rotates the text 
in a clockwise direction. 


4. Angles that are integer multiples of 180° display text horizontally. 
5. Angles that are integer multiples of 90° display text vertically. 
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OPTION ANGLE = DEGREES 

OPTION TYPE = EXPLICIT 

SET TEXT FONT -3, "STROKE" 

SET TEXT HEIGHT 0.05 

SET TEXT ANGLE 90 

GRAPH TEXT AT 0.7,0.55 : "90 degrees" 
SET TEXT ANGLE 180 

GRAPH TEXT AT 0.45,0.55 : "180 degrees" 
SET TEXT ANGLE 270 

GRAPH TEXT AT 0.5,0.55 : "270 degrees" 
SET TEXT ANGLE 0 

GRAPH TEXT AT 0.0,0.05 : "The default angle" 


Output 


50 degrees 


sasibop gel N 
o 
jan 
ist 
[sme 
ng 
Dp 
vy 


The default angle 


ee 
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>ET TEXT COLOR 


The SET TEXT COLOR statement allows you to specify the color of text 
characters. 


ormat 
SET TEXT COLOR = int-exp 


yntax Rules 


Int-exp must be a valid color value for all devices in use, and must be 
greater than zero. 


emarks 


1. Changing the text color affects the display of text on all active devices. 
You cannot specify a particular device with this statement. 


2. Changing color values may affect the shading on some black and 
white devices. 


3. The actual colors displayed are device dependent. If you set the color 
to an index value that is undefined for a particular device, results are 
unpredictable. 


4. On VT125 and VT240 terminals with the color option, the default 
values for int-exp represent the following colors: 


Index Color 
0 Black 
1 Green 
2 Red 

3 Blue 


5. See also the SET COLOR MIX statement for related information. 
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PROGRAM colorful 
DECLARE SINGLE concat_x, 


SET TEXT HEIGHT 0.2 

SET TEXT COLOR 2 

GRAPH TEXT AT 0.0,0.5 : 
ASK TEXT POINT , "C" AT 
SET TEXT COLOR 3 

GRAPH TEXT AT concat_x, 
ASK TEXT POINT , "o" AT 
SET TEXT COLOR i 

GRAPH TEXT AT concat_x, 
ASK TEXT POINT , "1" AT 
SET TEXT COLOR 2 

GRAPH TEXT AT concat_x, 
ASK TEXT POINT , "o" AT 
SET TEXT COLOR 3 

GRAPH TEXT AT concat_x, 
ASK TEXT POINT , "r" AT 
SET TEXT COLOR 1 

GRAPH TEXT AT concat_x, 
ASK TEXT POINT , "f£" AT 
SET TEXT COLOR 2 

GRAPH TEXT AT concat_x, 
ASK TEXT POINT , "u" AT 
SET TEXT COLOR 3 

GRAPH TEXT AT concat_x, 


END PROGRAM 
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concat_y 


"cr 
0.0,0.5 : 


concat_y : 


concat_x, 


concat_y : 


concat_x, 


concat_y : 


concat_x, 


concat_y : 


concat_x, 


concat_y : 


concat_x, 


concat_y : 


concat_x, 


concat_y : 


concat_x, 


Non 


concat_y: 


“yn 


concat_y : 


Hot 


concat_y : 


ty 
concat_y 


ug 


concat_y : 


my" 


concat_y : 


oye 


concat_y 


concat_x, concat_y 


concat_x, concat_y 


concat_x, concat_y 


:concat_x, concat_y 


concat_x, concat_y 


concat_x, concat_y 


SET TEXT COLOR 


Output 


( rs 
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SET TEXT EXPAND 


The SET TEXT EXPAND statement lets you change the ratio of character 
width to height from the ratio defined in the original font design. 


Format 


SET TEXT EXPAND real-exp 
Syntax Rules 


Real-exp must be greater than zero. 


Remarks 
1. The default width to height ratio is 1.0, which specifies the expansior 
ratio defined in the font design. 
2. The value you assign to real-exp is the expansion factor used in 
subsequent GRAPH TEXT statements and stays in effect until anothe: 
SET TEXT EXPAND statement is executed. 
Example 


SET TEXT FONT -3, "STROKE" 
SET TEXT HEIGHT 0.05 


SET TEXT EXPAND 3 

GRAPH TEXT AT 0,0.8 : "Fat" 
SET TEXT EXPAND 1 

GRAPH TEXT AT 0,0.6 : "Normal" 
SET TEXT EXPAND 0.5 

GRAPH TEXT AT 0,0.4 : "Thin" 
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SET TEXT EXPAND 
Output 
pees 32> ee 


Normal 


Thin 


eae 
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SET TEXT FONT 


The SET TEXT FONT statement lets you select a font and specify the le 
of precision with which the characters are drawn. 


Format 


SET TEXT FONT = int-exp [ , str-exp ] 
Syntax Rules 


Int-exp specifies the font number. 


2. The optional str-exp specifies the level of precision with which the 
font characters are drawn. 


Remarks 


The default font is font -1, which is displayed with STROKE precis: 


2. Hardware fonts are device dependent. When no hardware fonts 
are available, software fonts are used. Software fonts are device 
independent and provide a graphical representation of the defined 
characters. Depending on the device, hardware fonts are usually 
displayed faster than software fonts. 


3. If the precision string is not included, the specified software font is 
displayed with STROKE precision by default. 


4. Hardware fonts can be displayed with either STRING or CHAR 
precision. If a hardware font is requested with STROKE precision, 
software font that is closest in number to the font you specify will 
displayed. 

5. Software fonts can be drawn only with STROKE precision which 
provides an accurate representation of the text characters as specifi 
in the font design. Software fonts can be displayed with only STRC 
precision. If you specify an alternative precision string, a hardware 
font will be displayed. 
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The number of hardware and software fonts is device dependent. 

If you specify that a font be displayed with a precision that is not 
available on a particular device, an alternative font will be displayed 
with the precision you specify. VT125 and VT240 fonts are dis- 
played throughout this manual. VAXstation fonts are displayed in 
Appendix B. 


STRING Precision 


STRING precision is available only for hardware fonts. STRING 
precision uses the device-specific character style defined in the font 
design. The starting position of the string is guaranteed to start at the 
same point as is defined in the font design. However, attributes such 
as the text path, alignment, angle, and spacing are not guaranteed to 
match the specifications in the font design. 


When clipping is enabled, STRING precision clips text on a string 
basis at the world viewport boundary, This means that no text string 
starts beyond the world viewport boundary. 


CHAR Precision 


CHAR precision is available only for hardware fonts. This preci- 
sion value uses the device-specific character style defined in the font 
design, as STRING precision does. However, this precision guaran- 
tees the text height, character expansion factor, spacing, angle, and 
alignment as much as is possible for a given device. 


When clipping is enabled, CHAR precision clips text at least on a 
character-by-character basis at the world viewport. This means that no 
character extends beyond the world viewport boundary. Depending 
on the capabilities of the device, character clipping is either partial or 
complete. 


STROKE Precision 


STROKE precision is available only for software fonts. STROKE 
precision displays characters with the most accuracy. In addition, 
clipping is more precise with STROKE precision. When clipping is 
enabled, STROKE precision clips text precisely at the world viewport 
boundary. This means that if only half a character falls inside the 
world viewport boundary, only this half is displayed on the screen. 
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OPTION TYPE = EXPLICIT 
DECLARE LONG variety 
SET WINDOW 0,100,0,100 
SET TEXT HEIGHT 3 
FOR variety = -1 TO -23 STEP -1 
SET TEXT FONT variety , "STROKE" 
IF variety > -13 
THEN 
GRAPH TEXT AT 0,100-(ABS(variety) * 8) 
ELSE 
GRAPH TEXT AT 50,100-((ABS(variety) * 8) 
END IF 
NEXT variety 
END 


Output 


: "Font No. " + STR$(variety) 


: "Font No. " + STR$(variet: 


- 90) 





Font No. -1 





Font No. -73 


FOSVY NG, -2 
Font No, —3 Eouy Ho. -14 
Zofu =o. —4 Font No, -15 


vant lie, —& 
Font No. -6 
ZOEV Bo. —7 
Font No. -8 
Font No, -—9 
Zotv Zo. -10 
Font No, -7f 
Fant No, -12 


Bog Bey 
sap ye 


hte 


ole! 


Sat 


net 


$5. 


Font No, -16 
ont No. ~17 
Font Wo, -18 
Pant Do. <1 
Ysa( oof Puff 
HHI®): 


i 


A 
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SET TEXT HEIGHT 


‘T TEXT HEIGHT 


‘mat 


The SET TEXT HEIGHT statement lets you change the height of the 
characters in a font. 


ET TEXT HEIGHT _real-exp 


itax Rules 


marks 


Real-exp must be greater than zero. 


Height refers to the height of the uppercase letters in world coordi- 
nates. Lowercase characters are sized proportionally. 


The value of real-exp must be greater than zero. 
At the start of program execution, the text height is 0.035. 


When you change the boundaries of the world window, you may 
need to adjust the text height to a value that is suitable for the new 
window size. To regain a text height equivalent to the default height 
after setting the window, use the following formula: 


new_height = (max_height - min_height) * 0.035 
For example: 

SET WINDOW 0,100, 1000,5000 

new_height = (5000 - 1000) * 0.035 

SET TEXT HEIGHT new_height 


For CHAR and STRING precision, the text height is set to the nearest 
possible value to your request. For STROKE precision, text size is 
matched accurately. 
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6. When you invoke a picture with transformation functions in the 
DRAW statement, the text height and the text starting point are no 
automatically adjusted. You account for these transformations by 
using the TRANSFORM function, as shown in the example for the 
TRANSFORM function in this chapter. 


SET WINDOW 0,100,0,100 

SET TEXT FONT -3, "STROKE" 

SET TEXT HEIGHT 4 

GRAPH TEXT AT 0,50 : "BIG..." 

SET TEXT HEIGHT 7 

GRAPH TEXT AT 10,50 : "BIGGER..." 
SET TEXT HEIGHT 10 

GRAPH TEXT AT 40,50 :"BIGGER..." 


Output 


_—_— 


sic..BIGGER,.. BIGGER... 





Oe 
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SET TEXT JUSTIFY 


The SET TEXT JUSTIFY statement allows you to change the values of the 
current horizontal and vertical components of text justification. 


mat 


ET TEXT JUSTIFY = str-exp!, str-exp2 


itax Rules 


1. You specify the value for the horizontal component in str-exp1 and the 
value for the vertical component in str-exp2. 


2. Possible values for the horizontal component in str-exp1 are as follows: 


Value 
LEFT 


CENTER 


RIGHT 


NORMAL 


Effect on Horizontal Component 


Corresponds to the left side of the text box passing through 
the text position 


Corresponds to the text position lying midway between the 
left and right sides of the text box 


Corresponds to the right side of the text box passing through 
the text position 


Depends on the text path—see remark #3 
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3. Possible values for the vertical component in str-exp2 are as follow 


Value Effect on Vertical Component 

TOP The top of the text box passes through the text position. 

CAP The text position passes through the capline of the whol 
string. 

HALF The text position passes through the half-line of the whc 
string. 

BASE The text position lies on the baseline of the whole string 

BOTTOM The bottom of the text box passes through the text. 

NORMAL See remark #3. 


Remarks 


1. When a SET TEXT JUSTIFY statement is executed, the two string 
variables are evaluated to establish an imaginary box surrounding 
subsequent text output. The box is relative to the starting point 
specified in a GRAPH TEXT statement. Text justification has two 
components: horizontal and vertical. 


2. The initial value for both the horizontal and the vertical componer 
is NORMAL. 


3. NORMAL can be specified for both the horizontal and vertical con 
ponents. NORMAL provides a natural justification for each text pa 
For each of the text paths the horizontal and vertical components < 


as follows: 

Normal Normal 
Text Path Horizontal Vertical 
RIGHT LEFT BASE 
LEFT RIGHT BASE 
UP CENTER BASE 
DOWN CENTER TOP 


« 
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SET TEXT FONT -3, "STROKE" 

SET TEXT HEIGHT 0.04 

SET TEXT COLOR 2 

SET LINE COLOR 3 

SET TEXT JUSTIFY "NORMAL" , "TOP" 
GRAPH TEXT AT 0.4,0.9 : "Normal/top" 
GRAPH LINES 0.4,0.9; 0.7,0.9 


SET TEXT JUSTIFY "NORMAL" , "BOTTOM" 
GRAPH TEXT AT 0.4,0.7 : "Normal/bottom" 
GRAPH LINES 0.4,0.7; 0.7,0.7 


SET TEXT JUSTIFY "LEFT" , "NORMAL" 
GRAPH TEXT AT 0.4,0.5 : "Left/normal" 
GRAPH LINES 0.4,0.5; 0.7,0.5 


SET TEXT JUSTIFY "CENTER" , "NORMAL" 
GRAPH TEXT AT 0.4,0.3 : "Center/normal" 
GRAPH LINES 0.4,0.3; 0.7,0.3 

SET TEXT JUSTIFY "RIGHT" , "NORMAL" 
GRAPH TEXT AT 0.4,0.1 : "Right/normal" 
GRAPH LINES 0.4,0.1; 0.7,0.1 


Output 


SET TEXT JUSTIFY 


hs 





SS TST 
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SET TEXT PATH 


The SET TEXT PATH statement lets you specify the direction in which 
characters are drawn. 


Format 


SET TEXT PATH _ str-exp 
Syntax Rules 


Str-exp can be one of the following values (in lower- or uppercase): 


e RIGHT 
e LEFT 

e UP 

¢ DOWN 


Remarks 


1. Path refers to the direction in which the text is written relative to th 
text angle. 


2. The default value for str-exp is RIGHT. 
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SET TEXT FONT -3, 
SET TEXT HEIGHT 0.05 


SET TEXT PATH 
GRAPH TEXT AT 
SET TEXT PATH 
GRAPH TEXT AT 
SET TEXT PATH 
GRAPH TEXT AT 
SET TEXT PATH 
GRAPH TEXT AT 


Output 


"STROKE" 


"yp 


0.1,0.1 : 
"LEFT" 
0.7,0.9 : 
"DOWN" 
0.2,0.9 : 
"RIGHT" 
0.5,0.5 : 


"UP PATH" 


"LEFT PATH" 


"DOWN PATH" 


"RIGHT PATH" 


SET TEXT PATH 


{ HTAP TFEL \ 


> HT 


Td 


D 


RIGHT PATH 
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SET TEXT SPACE 


The SET TEXT SPACE statement lets you change the spacing between 
characters drawn on an output device. 


Format 
SET TEXT SPACE _real-exp 


Syntax Rules 
None. 
Remarks 


1. Subsequent GRAPH TEXT statements use the spacing specified in 
real-exp until another SET TEXT SPACE statement is executed. 


2. Space refers to the distance between adjacent characters. The distan 
is expressed as a fraction of the text height. 


3. The default value for the spacing is 0, which produces adjacent 
characters as defined in the font design. 


4. A positive value for real-exp inserts space between characters. 
5. A negative value for real-exp causes characters to overlap. 
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t+ 

!Set text height to 5/100 of the default window 

f= 

SET TEXT HEIGHT 0.05 

SET TEXT FONT -16, "STROKE" 

SET TEXT SPACE 0.09 

GRAPH TEXT AT 0,0.8 : "These characters are far out" 
SET TEXT SPACE 0 

GRAPH TEXT AT 0,0.6 : "This is the normal spacing" 
SET TEXT SPACE -0.09 

GRAPH TEXT AT 0,0.4 : "These characters are tight" 


Output 


Lee 


These characters are far out 
Thia is the normal spacing 


These characters are tight 


Ie 
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SET TRANSFORMATION 


The SET TRANSFORMATION statement explicitly establishes the trans- 
formation to be used for subsequent interpretations of world coordinate 
points. 


Format 
SET TRANSFORMATION _int-exp 


Syntax Rules 
Int-exp must be between 1 and 255. 
Remarks 


1. The current transformation number is set to the number you specify i: 
int-exp. The default transformation is 1. 


2. An implicit SET TRANSFORMATION is performed when a SET 
WINDOW or SET VIEWPORT statement is executed. 


3. This transformation is used to display graphics output until a differen 
transformation is established in a SET TRANSFORMATION, SET 
WINDOW, or SET VIEWPORT statement. 

4. A SET TRANSFORMATION statement is invalid within a picture 
definition. 

5. A SET TRANSFORMATION statement implicitly sets the highest 
input priority to be the specified transformation. When conflicting 
viewports are defined, the transformation with the highest input 


priority is used to interpret input points. See also the SET INPUT 
PRIORITY statement. 
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‘Xample 


SET TRANSFORMATION 


SET WINDOW , TRAN 1 : 0,10,0,10 

SET VIEWPORT , TRAN 1 : 0,0.5,0,0.5 
SET WINDOW , TRAN 2 : 500,1000,1,10 
SET VIEWPORT ,TRAN 2 : 0.5,1,0.5,1 
SET TRANSFORMATION 1 

GRAPH AREA 2,8; 7,6; 3,1 

SET TRANSFORMATION 2 

GRAPH POINTS 800,2; 450,8; 475,8.5 
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SET VALUE ECHO AREA 


The SET VALUE ECHO AREA statement lets you specify the boundaries 
of the VALUE echo area. 


Format 
SET VALUEECHO AREA | *2ev-id : 
, UNIT int-exp 
real-exp1, real-exp2, real-exp3, real-exp4 
Syntax Rules 
1. Real-exp1, real-exp2, real-exp3, and real-exp4 must be floating-point 
expressions to represent the left, right, bottom, and top boundaries 
respectively. 
2. When specified, dev-id must be the first clause listed and must be 
preceded by the number sign (#). 
3. If one or more optional clauses are included, one colon (:) is required 
before real-exp1. 
Remarks 


The echo area is the portion of your screen where the prompt appear: 
and where input can be supplied by a user. 


The optional dev-id identifies the device for which you want to set th 
echo area. If no identification clause is included, VAX BASIC uses a 
default identification of #0. If an identification clause is included, the 
device specified must have been opened explicitly or opened by VAX 
BASIC as the default device. 
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3. Boundaries must be specified in device coordinates. To determine 
the possible values on a particular device, use the ASK DEVICE 
SIZE statement. To determine the current boundaries, use the ASK 
VALUE ECHO AREA statement. Appendix B lists the boundaries for 
VAXstations and VT125 and VT240 terminals. 


4. The default echo area for VALUE input is device dependent. The 
default area is in effect until a SET VALUE ECHO AREA statement is 
executed. 


5. The optional UNIT clause allows you to specify an alternative means 
of supplying the input. For instance, the position of points can be 
entered with mouse, or with the keyboard arrow keys. Each of these 
methods of data entry is a different unit. The default unit value for 
int-exp for each input type is 1; the default is used throughout this 
manual. For information about the units available on a particular 
device, see the hardware documentation for that device, as well as the 
VAX GKS documentation. 


6. On devices that display the VALUE range limits, the size and justifi- 
cation of the characters cannot be altered. You should ensure that the 
VALUE echo area is appropriate for the VALUE prompt for the device 
you use. 


7. Subsequent requests for each input type use the echo boundaries you 
supply until another SET VALUE ECHO AREA statement is executed. 


OPTION TYPE = EXPLICIT 
DECLARE SINGLE left_1,right_1,bottom,top,input_value 
OPEN “office-term" FOR GRAPHICS AS DEVICE #1 


ASK VALUE ECHO AREA #1 : left_1,right_1, bottom, top 

1+ 

!Set the echo area to the top corner of the default area 

1- 

SET VALUE ECHO AREA #1 : left_1 & 
»right_1 & 
, (top-bottom) /2 & 
, top 

LOCATE VALUE #1 : input_value 
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SET VIEWPORT 


The SET VIEWPORT statement allows you to change the section of NDC 
space to which an image in the world window is mapped. 


Format 


SET VIEWPORT /, TRAN int-exp: | real-exp1, real-exp2, real-exp3, real-exp4 
Syntax Rules 


1. Real-exp1, real-exp2, real-exp3, and real-exp4 must be floating-point 
expressions to represent the left, right, bottom, and top boundaries 
respectively. Values must be within the range 0.0 to 1.0. 


2. Int-exp must be between 1 and 255. 
Remarks 


1. The world viewport represents a portion of the abstract display 
surface known as the Normalized Device Coordinate space (NDC 
space). World coordinates are mapped to NDC space according to the 
specified boundaries in a SET VIEWPORT statement. 


2. The default world viewport consists of the complete NDC space. The 
boundaries at the start of program execution are 0,1,0,1 for the left, 
right, bottom, and top boundaries respectively. 


3. Viewport boundaries must be within the range 0.0 to 1.0. 


4. The SET VIEWPORT statement implicitly establishes the current 
transformation. 


5. You can set a different world viewport for separate parts of your 
application, provided that you specify a different transformation 
number for each. For instance, the following statements set up the 
world viewport boundaries of 0,0.5,0.5,1 for transformation 1, and 
boundaries of 0.5,1,0.5,1 for transformation 2. 
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SET VIEWPORT , TRAN 1 : 
SET VIEWPORT , TRAN 2 : 


. 


6. If you do not specify a transformation with the optional TRAN clause, 
the default transformation of 1 is assumed. At the start of program 
execution, transformation 1 defines the default window (0,1,0,1) and 
the default viewport (0,1,0,1). 


7. All subsequent graphics output is interpreted using transformation 
int-exp until an alternative transformation is established in a SET 
TRANSFORMATION, SET WINDOW, or SET VIEWPORT statement. 


8. A SET VIEWPORT statement implicitly sets the highest input priority 
to be the specified transformation. When conflicting viewports are 
defined, the transformation with the highest input priority is used to 
interpret input points. See also the SET INPUT PRIORITY statement. 


9. The specified viewport boundaries remain in effect for transformation 
int-exp unless other boundaries are specified in a subsequent SET 
VIEWPORT statement referring to the same transformation. 


10. A SET VIEWPORT statement is invalid within a picture. 


EXTERNAL PICTURE swan 


SET WINDOW , TRAN 2 : 0,100,0,100 
!'Map all of window to top right corner of NDC space 
SET VIEWPORT , TRAN 2 : 0.5,1,0.5,1 


SET TRANSFORMATION 2 
DRAW swan 


VAX BASIC Graphics Statements 9-227 


SET VIEWPORT 


Output 
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SET WINDOW 


The SET WINDOW statement lets you change the boundary values (and 
therefore the coordinate measures) for the world window. 


Format 


SET WINDOW 


Syntax Rules 


Remarks 


[, TRAN int-exp: J] real-exp1, real-exp2, real-exp3, real-exp4 


Real-exp1, real-exp2, real-exp3, and real-exp4 must be floating-point 
expressions to represent the left, right, bottom, and top boundaries 
respectively. 


Int-exp must be between 1 and 255. 


The default world window boundaries are 0,1,0,1 for the left, right, 
bottom, and top boundaries respectively. 


When no transformation is specified, the transformation is set to 
transformation 1, the default. 


The SET WINDOW statement implicitly establishes the current trans- 
formation. 


The specified window boundaries remain in effect for transformation 
int-exp unless other boundaries are specified in a subsequent SET 
WINDOW statement referring to the same transformation. 


All subsequent graphics output is interpreted using transforma- 
tion int-exp until another transformation is established in a SET 
TRANSFORMATION, SET WINDOW, or SET VIEWPORT statement. 


A SET WINDOW statement implicitly sets the highest input priority 
to be the specified transformation. When conflicting viewports are 
defined, the transformation with the highest input priority is used to 
transform input points. See also the SET INPUT PRIORITY statement. 
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7. When clipping is enabled with the SET CLIP “ON” statement, graphics 
images with world coordinate values exceeding the limits of the world 
window are not displayed. 


8. When clipping is disabled with the SET CLIP “OFF” statement, images 
with world coordinate values that exceed the limits of the world 
window are displayed, provided that the points are also within the 
device window. 


9. After a SET WINDOW statement, you may need to use the SET TEXT 
HEIGHT statement to increase the text height. 


10. A SET WINDOW statement is invalid within a picture. 


Example 


t+ 

'Each of these output statements displays the center point 
I- 

GRAPH POINTS 0.5,0.5 

CLEAR 


SET WINDOW , TRAN 1: 0,100,0,100 
GRAPH POINTS 50,50 
CLEAR 


SET WINDOW , TRAN 2 : 25,525,0,1000 
GRAPH POINTS 275,500 
CLEAR 


SET WINDOW , TRAN 3 : -1,1,-1,1 
GRAPH POINTS 0,0 

CLEAR 

SET WINDOW , TRAN 4 : -50,0,0,900 
GRAPH POINTS -25,450 
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SHEAR 


When used in a DRAW statement, the SHEAR function skews the x- 
coordinates of points specified in a PICTURE subprogram. SHEAR can 
also be used in the MAT statement to create a new matrix. 


Format 


In the DRAW Statement 
DRAW _pic-name[(param-list)] WITH SHEAR (angle) [ * matrix2]... 


In the MAT Statement 
MAT matrix? = SHEAR(angle) [ * matrix2]... 


Syntax Rules 


1. Angle can be in radians or degrees, depending on the option you 
specify with the OPTION ANGLE statement. The default is radians. 


2. Matrix1 and matrix2 must be two-dimensional numeric arrays that are 
zero-based with upper bounds of 4 in both directions. VAX BASIC 
signals a compile-time error when the compiler detects a nonzero- 
based matrix; otherwise, a run-time error is signaled. Packed decimal 
arrays are invalid. 


3. Matrix2 can also be one of the valid transformation functions from the 
DRAW statement, including the following: 


¢ ROTATE 
e SCALE 
e SHIFT 


¢ TRANSFORM 


VAX BASIC Graphics Statements 9-231 


SHEAR 


Remarks 


1. SHEAR can be used only on the right side of a MAT statement or as a 
transformation function in the DRAW statement. 


2. Like other transformation functions, the SHEAR function affects 
coordinates displayed with PLOT and MAT PLOT statements within 
pictures. Similarly, input points accepted with GET and MAT GET 
statements within a picture definition are affected by the inverse of a 
SHEAR function specified on the DRAW statement that invokes the 
picture. 


3. For an example and more information, see the DRAW statement in 
this chapter. 
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SHIFT 


When used in a DRAW statement, the SHIFT function moves the coordi- 
nates of points specified in a PICTURE subprogram. SHIFT can also be 
used in the MAT statement to create a new matrix. 


Format 


In the DRAW Statement 
DRAW _pic-name[(param-list)] WITH SHIFT (real-exp 1, real-exp2) [ * matrix2 ]... 


In the MAT Statement 
MAT matrix? = SHIFT (real-exp1, real-exp2) [ * matrix2]... 


Syntax Rules 


1. Real-exp1 is applied to the x-coordinate of a point. 
Real-exp2 is applied to the y-coordinate of a point. 


3. Matrix1 and matrix2 must be two-dimensional numeric arrays that are 
zero-based with upper bounds of 4 in both directions. VAX BASIC 
signals a compile-time error when the compiler detects a nonzero- 
based matrix; otherwise, a run-time error is signaled. Packed decimal 
arrays are invalid. 


4. Matrix2 can also be one of the valid transformation functions from the 
DRAW statement, including the following: 


e ROTATE 
e SCALE 
e SHEAR 


¢ TRANSFORM 
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SHIFT 


Remarks 


SHIFT can be used only on the right-hand side of a MAT statement or 
as a transformation function in the DRAW statement. 


Negative values for real-exp1 shift x-coordinates to the left; positive 
values shift coordinates to the right. 


Negative values for real-exp2 shift y-coordinates lower on the display 
surface; positive values shift coordinates up. 


Like other transformation functions, the SHIFT function affects co- 
ordinates displayed with PLOT and MAT PLOT statements within 
pictures. Similarly, input points accepted with GET and MAT GET 
statements within a picture definition are affected by the inverse of 
a SHIFT function specified on the DRAW statement that invokes the 
picture. 


For an example and more information, see the DRAW statement in 
this chapter. 
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TRANSFORM 


TRANSFORM 


The TRANSFORM function returns the cumulative transformation for all 
transformation clauses in current picture invocations. 


Format 


In the DRAW Statement 
DRAW _pic-name[(param-list)] WITH TRANSFORM [ * matrix2]... 


In the MAT Statement 
MAT matrix! = TRANSFORM [ * matrix2/... 


Syntax Rules 


1. Matrix1 and matrix2 must be two-dimensional numeric matrices that 
are zero-based with upper bounds of 4 in both directions. VAX BASIC 
signals a compile-time error when the compiler detects a nonzero- 
based matrix; otherwise, a run-time error is signaled. Packed decimal 
arrays are invalid. 


2. Matrix2 can also be one of the valid transformation functions from the 
DRAW statement, including the following: 


¢ SHIFT 

e SCALE 

e ROTATE 
e SHEAR 
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TRANSFORM 


Remarks 


TRANSFORM can be used only on the right-hand side of a MAT 
statement or as a transformation function in the DRAW statement. 


When used within picture invocations, TRANSFORM contains the 
cumulative matrix for all current transformations. 


The current transformation is passed to any pictures by default. 
Therefore, if you use the TRANSFORM function inside a picture, the 
transformation in the DRAW statement will be applied twice. 


If no picture has been invoked with a DRAW statement, TRANSFORM 
returns the identity matrix. The identity matrix has no effect on a. 
graphics display. 

Like other transformation functions, the TRANSFORM function affects 
coordinates displayed with PLOT and MAT PLOT statements within 
pictures. Similarly, input points accepted with GET and MAT GET 
statements within a picture definition are affected by the inverse of a 
TRANSFORM function specified on the DRAW statement that invokes 
the picture. 


The TRANSFORM function can be used to adjust the text starting 
point and text height when text is drawn within a picture. The 
following example illustrates how to do this. Note that you cannot 
make adjustments for the text attributes for the ROTATE, SHEAR, and 
negative SCALE functions. 


For an additional example and more information, see the DRAW 
statement in this chapter. 


PROGRAM transform_text 


'+ 


!This program uses the TRANSFORM function to adjust the text height 
'and text starting point for a GRAPH TEXT statement in a picture 
!These attributes would not otherwise be affected by the 
transformation functions on a DRAW statement. 


OPTION TYPE = EXPLICIT 

EXTERNAL PICTURE box(STRING, SINGLE, SINGLE) 

DRAW box("No. 1",0.5,0.375) WITH SCALE(0.5) * SHIFT( 0.2, 0.1) 
DRAW box("No. 2",0.5,0.375) WITH SCALE(0.25) * SHIFT(0.3, 0.6) 
END PROGRAM 
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TRANSFORM 


PICTURE box(STRING box_name, SINGLE x,y) 
OPTION TYPE = EXPLICIT 
DECLARE SINGLE height, new_height(1,4), old_height(1,4), 
new_height_top, new_height_botton, 
new_x(1,4), new_y(1,4), 
old_x(1,4), old_y(1,4), 
LONG counter 
PLOT LINES 0,0; 0,.75; 1,.75; 1,0; 0,0 
{+ 
'Set the height of the letter to be one quarter 
tof the height of the box. 
‘Get the current transformation for this picture 
‘and transform the point. Take the y coordinate of the result 
‘and use it for the SET TEXT HEIGHT statement. 
{- 
old_height(1,counter) = 0.0 FOR counter = 0% TO 4% 
old_height(1,2) = .75/4 
old_height(1,4) = 1 
MAT new_height = old_height * TRANSFORM 
new_height_top = new_height(1,2) 


& & & & 


old_height(i,counter) = 0.0 FOR counter = 0% TO 4% 
old_height(1,2) = 0.0 

old_height (1,4) = 1 

MAT new_height = old_height * TRANSFORM 
new_height_bottom = new_height (1,2) 


old_x(1,counter) = 0.0 FOR counter = O% TO 4% 
old_x(1,1) =x 

old_x(1,4) = 1 

MAT new_x = old_x * TRANSFORM 


old_y(1,counter) = 0.0 FOR counter = 0% TO 4% 
old_y(1,2) = y 
old_y(1,4) = 1 


MAT new_y = old_y * TRANSFORM 


SET TEXT HEIGHT (new_height_top - new_height_bottom) 
SET TEXT FONT 1%, "STROKE" 
SET TEXT JUSTIFY "CENTER", "HALF" 
GRAPH TEXT AT new_x(1,1), new_y(1,2) : box_name 
END PICTURE 
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TRANSFORM 


Output 
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Appendix A 


Calling VAX GKS Directly 


VAX BASIC statements provide most of the features you will need to 
include graphics in your applications; however, you may choose to access 
additional graphics functionality by calling VAX GKS routines directly. 

In all instances, when VAX BASIC graphics statements are available, it is 
recommended that you use them rather than make direct calls yourself. 


.1 Introduction 


VAX GKS operates in one of four states. The states are 


¢ Closed 

¢ Open 

e At least one device open 
¢ At least one device active 


VAX BASIC controls the VAX GKS states for you by default. For instance, 
if you try to display output on a device when none is open and active, 
VAX BASIC opens and activates the default device for you. Similarly, if 
you try to close a device that you have not opened, VAX BASIC ignores 
your request to close it. 
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You must ensure that VAX GKS is in the correct operating state by using 
VAX GKS control routines in either of the following situations: 


¢ When a program includes no VAX BASIC graphics statements at all, 
but does include direct calls to VAX GKS routines 


e When a program makes direct calls to VAX GKS routines before 
executing any VAX BASIC graphics statements 


When VAX GKS is not in the correct state, an error is issued and pro- 
gram execution terminates. Consult the VAX GKS documentation for 
information about particular routines and the related error messages. 


VAX BASIC sets up many preferred defaults that do not always agree witl 
the VAX GKS defaults for a particular routine. The reference section in thi 
manual lists the defaults for each VAX BASIC graphics statement. Most 
of the VAX BASIC defaults that are device specific are set up when a VA) 
BASIC graphics output statement is executed or when an OPEN ... FOR 
GRAPHICS statement is executed. If you have already used VAX GKS 
routines in your program, other defaults may be in place. The following 
list includes items that you should be aware of when you make direct call 
to VAX GKS. 


e If you want VAX BASIC graphics defaults, be sure to use the 
OPEN ... FOR GRAPHICS statement, or include a graphics output 
statement before you make any direct calls to VAX GKS. 


e If you want VAX GKS defaults, you should open a device with explic 
calls to GKS$OPEN_WS and GKS$ACTIVATE_WS to override the 
VAX BASIC defaults. Note that when you use VAX GKS control 
statements, VAX GKS should be opened with an error file of “NLAO” 
This is important for VAX GKS error handling. You should be aware 
of the different defaults and use caution when mixing VAX BASIC 
graphics statements with direct calls to VAX GKS because program 
output can be unpredictable. 


¢ In VAX BASIC, transformation 0 is reserved and any references to 
transformation 0 in program statements are invalid. When you make 
direct calls to VAX GKS routines, transformation 0 is accessible. 
Nonetheless, you cannot change the priority of transformation 0 whe: 
calling VAX GKS routines from VAX BASIC programs. 


e The default text expansion factor of 1 is the height-to-width ratio 
defined in the font design. VAX BASIC maintains this “normal” ratio 
regardless of the current window boundaries. That is, whenever a 
new transformation becomes current, VAX BASIC implicitly adjusts 
the text expansion factor according to the ratio of the current windov 
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width to the current window height. However, VAX GKS produces a 
“normal” text expansion factor only when the world coordinate units 

for the x- and y-axes are the same. When you make direct calls to VAX 
GKS, you must make your own adjustments to the expansion factor when 
necessary. 


The following sections show you how to call VAX GKS routines directly 
and provide examples of such calls. The VAX GKS routines are described 
fully in the VAX GKS documentation. 


Like other system routines, each VAX GKS routine has an entry point 
(the routine name) and an argument list. It may also return values to 
the program that calls it. To call VAX GKS routines directly, you should 
follow these steps: 


1. Declare the desired VAX GKS routines with the EXTERNAL statement 
2. Declare all arguments with correct data types and passing mechanisms 
3. Call the desired routines 

4. Check the return status of the call 


\.2 Declaring VAX GKS Routines 


As with other system routines, you should declare VAX GKS routines 

as external functions rather than subprograms. To do this, use the 
EXTERNAL statement as shown in the following examples. Note that 

if you call a VAX GKS routine as a subprogram, you cannot check the 
status of the call. The following partial program illustrates how to make a 
simple call to a VAX GKS routine. 
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Example 


PROGRAM screen_makeup 
OPTION TYPE = EXPLICIT 


t+ 


!'Declare the routine as a function 
fe 


EXTERNAL LONG FUNCTION GKS$UPDATE_WS(LONG BY REF,LONG BY REF) 
EXTERNAL LONG CONSTANT STS$K_SUCCESS 
EXTERNAL SUB LIB$SIGNAL(LONG BY VALUE) 


V+ 


!Declare the arguments 
1- 


DECLARE LONG dev_id, flag_value ,return_status 
dev_id = 1% 


1+ 
!Call GKS$UPDATE_WS---this gives you control of the device 
!viewport (VAX BASIC performs this function by default when you define more t 


‘one device viewport and use VAX BASIC graphics statements) 
| - 


return_status = GKS$UPDATE_WS(dev_id, flag_value) 
{+ 


!'Check the status 


1- 
IF (return_status AND 1%) = STS$K_SUCCESS 
THEN GOTO device_setup 
ELSE CALL LIB$SIGNAL(return_status) 
EXIT PROGRAM 
END IF 


Arguments that are passed to VAX GKS functions must be listed in the 
order shown in the function descriptions in the VAX GKS documentation. 
Arguments are listed in the VAX GKS documentation as being write or 
modify, or read only. When VAX BASIC encounters arguments of the 
wrong data type, an error is signaled at compile time. VAX GKS expects 
the following data types and passing mechanisms: 


e Integer arguments as 32-bit longwords passed by reference 


e Real numbers in single-precision floating-point format passed by 
reference 


e Character strings passed by descriptor 


e Arrays passed either by reference or by descriptor, depending on the 
function 
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See the VAX GKS documentation to determine the rules governing the 
arguments you require for a particular function. 


\.3 Useful VAX GKS Routines 


Not all VAX GKS functionality is available with VAX BASIC statements. 
It is beyond the scope of this manual to illustrate the full extent of the 
additional functionality;. instead, three examples are provided here of 
functionality you can access by making direct calls to VAX GKS. The first 
example shows how to change the device echo type default (VAX BASIC 
offers a fixed default echo type). The second example show you how to 
use VAX GKS cell arrays. The third example illustrates the use of attribute 
bundles. 


..3.1 Changing the Echo Type 


The GKS$INIT_LOCATOR function allows you to take advantage of 
additional echo types for POINT input on VT125 and VT240 terminals. 
VAX BASIC supplies the VAX GKS default echo type, as illustrated in 
Chapter 7. To change this default, you must supply the alternative echo 
type as an argument to the GKS$INIT_LOCATOR routine. 


This example changes the echo type to 6. On VT125 and VT240 terminals, 
echo type 6 for POINT input consists of a display of the device coordinates 
of the point selected by a user. (Echo types are device dependent; consult 
the VAX GKS documentation for details.) 


With echo type 6, the position of the point is not displayed, only the 
coordinate values. The user can change the device coordinates with 

the arrow keys. The VAX GKS routine returns the equivalent world 
coordinates of this same point into two of the arguments you supply with 
the function call. The example displays the device coordinates and the 
world coordinates of the same point supplied by the user. 
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Example 


OPTION TYPE = EXPLICIT 
EXTERNAL LONG FUNCTION GKS$INIT_LOCATOR 
(LONG, LONG ,SINGLE, SINGLE, LONG ,LONG, 
SINGLE, ANY , LONG) 
EXTERNAL LONG CONSTANT STS$K_SUCCESS 
DECLARE SINGLE echo_area(3) 
DECLARE LONG tran_id, dev_id, return_status 
input _type_val,echo_type,data_size 
DECLARE SINGLE loc_x,loc_y,user_x,user_y 
t+ 
!This record is required but ignored by GKS 
= 
RECORD LOC_DATA_REC 
LONG loc_data 
END RECORD 


DECLARE LOC_DATA_REC rec1 
OPEN "" FOR GRAPHICS AS DEVICE #1 


dev_id = 1 
input_type_val = 1 


echo_area(0) = 240 
echo_area(1) = 767 
echo_area(2) = 0 

echo_area(3) = 479 


I+ 
'Initial point in world coords 

!User is presented with device coords of this point 
t- 
loc_x 
loc_y 
I+ 
!Set the new echo type 
f- 
echo_type 
data_size 


0.5 
0.5 


6%, 
0% 


return_status = GKS$INIT_LOCATOR(dev_id,input_type_val 
,loc_x,loc_y,tran_id,echo_type, echo_area() 
,reci,data_size) 
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IF (return_status AND 1%) = STS$K_SUCCESS 
THEN LOCATE POINT user_x,user_y 
ELSE EXIT PROGRAM return_status 
END IF 
t+ 
!Display world coordinates of user_x, user_y 
t- 
GRAPH TEXT AT 0,0.95 : "World coordinates: " + STR$(user_x) 
GRAPH TEXT AT 0,0.90 : STR$(user_y) 
END PROGRAM return_status 


Output 
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\.3.2 Using VAX GKS Cell Arrays 


The following example shows how to access the VAX GKS cell array 
feature. The example divides a rectangular area into cells and displays 
each cell in a specific color. To specify color, the example defines an array 
and supplies color index values as data to the array. 
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Example 


OPTION TYPE = EXPLICIT 
EXTERNAL LONG FUNCTION GKS$CELL_ARRAY (SINGLE ,SINGLE,SINGLE,SINGLE, 
LONG ,LONG ,LONG,LONG,LONG DIM (,)) 
EXTERNAL LONG CONSTANT STS$K_SUCCESS 
DECLARE SINGLE first_x, first_y, second_x, second_y 
DECLARE LONG no_rows, no_cols, start_row, start col, 
counter, inner,return_status 

DIM LONG colour(3,2) 
OPEN "" FOR GRAPHICS AS DEVICE #1 
t+ 
!'Fill the array with color index values 
1- 
DATA 3,2,0, 1,3,2, 0,2,2, 3,1,1 
FOR counter = 0% TO 3% 

FOR inner = 0% TO 2% 

READ colour (counter, inner) 

NEXT inner 

NEXT counter 


first_x = 0.2 
first_y = 0.3 
second_x = 
second_y = 
start_row = 0 
start_col = 0 
no_rows = 4%, 
no_cols = 3% 
return_status = GKS$CELL_ARRAY(first_x,first_y,second_x,second_y 
, start_row,start_col,no_rows ,no_cols,colour(,)) 

IF (return_status AND 1%) = STS$K_SUCCESS 

THEN 

CLOSE DEVICE #1 
END IF 
END 


s 


=~ 
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Output 
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1.3.3 Accessing Attribute Bundles 


When you call VAX GKS directly, you can change attributes in groups, 

or bundles. VAX BASIC provides the capability to change each of the 
attributes. of graphics objects individually. For instance, you can change 
the line style, the point color, and the text size. How to change the 
attributes is discussed in Chapter 3. With direct calls to VAX GKS routines, 
you can specify a set of predefined attribute values for an object. 


VAX GKS stores predefined attribute values for each object in a construct 
known as a bundle table. The bundle table consists of several sets of 
predefined attribute values; you specify an index in the bundle table 

to select a given set of attribute values for an object. Each hardware 
device has its own set of bundle tables. You can select from several sets 
of predefined values to achieve the image you want. For details of the 
bundle tables for a particular device, see the VAX GKS documentation. 
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The attributes are governed by Attribute Source Flags (ASFs). Each ASF 
can have a value of 0 for bundled, or 1 for individual. To specify an 
index to the bundle tables, you must call the routine GKS$SET_ASF to 
set selected ASFs to the value 0 for bundled. By default, each of the 
ASFs is set to 1. You must pass an array of 13 values (0 or 1 each) to the 
GKS$SET_ASF routine. The order of the flags in the bundle table is as 
follows: 


pond 


Line type 

Line width scale factor 
Line color index 

Point type 

Point size scale factor 
Point color index 

Text font and precision 
Character expansion factor 


CONAN RWN 


Character spacing 


— 
© 


. Text color index 


pod 
—_ 


. Fill area interior style 


— 
No 


. Fill area style index 
13. Fill area color index 


When program execution begins, all of these flags are set to indi- 
vidual (1). If no flag values are changed, then graphics objects are 
displayed with the individual VAX GKS default values. 


Note that VAX BASIC attribute statements do not change the ASFs; 
therefore, setting an ASF to bundled effectively disables some of the VAX 
BASIC SET statements and invalidates the corresponding ASK statements. 


The following example displays sample text using the initial text attri- 
butes. The example then sets a selection of the flags to 0 and calls the 
GKS$SET_ASF function specifying which bundle of attributes to use. The 
text is displayed again showing the bundled text attributes. 
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Example 


OPTION TYPE = EXPLICIT 

EXTERNAL LONG FUNCTION GKS$SET_ASF(LONG DIM () BY REF) 

DECLARE LONG flags(1 TO 13) 

DECLARE LONG counter, return_status 

EXTERNAL LONG CONSTANT STS$K_SUCCESS 

t+ 

{Initialize array to 1, for individual 

f- 

flags(counter) = 1 FOR counter = 1 TO 13 

t+ 

!Display text with individual defaults 

t- 

GRAPH TEXT AT 0.0,0.8 : "Text attributes set to individual." 

I+ 

!Change flags 7-10 to 0 for bundles 

1- 

flags(counter) = O FOR counter = 7% TO 10% 

1+ 

{Set the ASFs with the new array 

t- 

return_status = GKS$SET_ASF(flags()) 

I+ 

!'Check the return status 

!If success, display text with bundled attributes 

{- 

IF (return_status AND 1 
THEN GRAPH TEXT AT O. 
ELSE GRAPH TEXT AT 0. 

END IF 

END 


) = STS$K_SUCCESS 
0,0.5 : “Attributes from a bundle table." 
1,0.4 : "Error in GKS$SET_ASF" 


4 
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Appendix B 
Device Specifications 


This appendix lists information specific to the following DIGITAL devices: 


e VT125 and VT240 terminals 
e §6VAXxstations I, II, and II/GPX 


The initial and default values listed here refer to the selections available 
with VAX BASIC graphics statements. These devices support additional 
features (such as alternative echo styles) that are not available with VAX 
BASIC graphics statements. For more information, see the VAX GKS 
documentation. Information about other devices can also be found in 
the VAX GKS documentation, as well as in the documentation for the 
individual device. 


Section B.3 of this appendix provides a chart that lists and illustrates 
values for the color intensities of red, green, and blue that can be used on 
VT125 and VT240 terminals and VAXstations. 


B.1 V1T125 and VT240 Terminals 


This section describes the information needed to use VAX BASIC graphics 
with monochrome and color VT125 and VT240 terminals. 


Device Specifications B-1 


B.1.1 Device Types 


The following device types are valid: 


GKS$WSTYPE 
10 
11 
12 
13 
14 


B.1.2 Text Fonts 


Device 

VT125 monochrome, output only 
VT125 with color option 

VT125 monochrome 

VT240 with color option 


VT240 monochrome 


VT125 and VT240 terminals support one hardware font and 23 software 
fonts. These fonts are illustrated in Chapter 4 of this manual. 


B.1.3 Pattern Values 


The following table lists the values for the area style index when the area 
style is set to PATTERN. 


Style Index 


nan oO fF W NY 


B.1.4 Hatch Values 


Appearance 

Mixes colors 1 and 2 
Mixes colors 2 and 3 
Mixes colors 3 and 1 
Mixes colors 0 and 1 
Mixes colors 0 and 2 


Mixes colors 0 and 3 


The following table lists the values for the area style index when the area 
style is set to HATCH. Some of these indices are illustrated in Chapter 3. 
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Style Index Appearance 

Cross hatches 

Horizontal lines at 45 degrees 
Horizontal lines at -45 degrees 
Horizontal lines 

Vertical lines 

Horizontal lines at 45 degrees—sparse 
Horizontal lines at -45 degrees—sparse 


Horizontal lines—sparse 


Oo ON BD OO FF W NY 


Vertical lines—sparse 
10-19 Varying density hatches! 
33-126 Hatching with the corresponding ASCII character 


a varying density hatch style is a mixture of pixels of a given color and white pixels, which gives 
the appearance of different shades. For hatch styles 10 through 19, the hatches progress from lighter 
to darker; 10 being the lightest and 19 being the darkest. 


1.5 Device Coordinates 


The VT125 device coordinates have the range ([0,767] x [0,479]); the 
VT240 device coordinates have the range ([0,799] x [0,479]). 


.1.6 Input Constructs 


On VT125 and VT240 terminals, you press the RETURN key to indicate 
the completion of input. You use the arrow keys to move the cursor. For 
POINT, MULTIPOINT, and VALUE input, you can also use the PF3 key 
to move the cursor a shorter distance and the PF4 key to move the cursor 
a greater distance. 
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B.1.6.1 POINT Input 
The default values for POINT input on VT125 and VT240 terminals are as 


follows: 

Input Construct Default Value 

Unit 1 

Initial cursor position (0.5, 0.5) in world coordinates 

Echo area [(0,479.0) x (0,479.0)] in device coordinates 


B.1.6.2 MULTIPOINT Input 


When you enter MULTIPOINT input, press the space bar to enter each 
point and press RETURN when the series of points is complete. A line is 
displayed that joins successive points in the series of points entered. The 
DELETE key eliminates the last point entered. 


The default values for MULTIPOINT input on VT125 and VT240 terminal: 
are as follows: 


Input Construct Default Value 

Unit 
Initial number of points 0 

Echo area {(0,479.0) x (0,479.0)] in device coordinates 
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1.6.3 CHOICE Input 
The default values for CHOICE input on VT125 and VT240 terminals are 


as follows: 

Input Construct Default Value 

Unit 
VT125 echo area {(513.0,767.0) x (0,479.0)] in device coordinates 
VT240 echo area {(533.0,767.0) x (0,479.0)] in device coordinates 
Initial number of choices 5 

Initial choice 1 

Default menu “CHOICE 1”, “CHOICE 2”, and so on through 


“CHOICE 5“ 


1.6.4 STRING Input 
The default values for STRING input on VT125 and VT240 terminals are 


as follows: 

Input Construct Default Value 

Unit 
Initial string Null 

VT125 echo area [((513.0,767.0) x (0,479.0)] in device coordinates 
VT240 echo area [(533.0,767.0) x (0,479.0)} in device coordinates 
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B.1.6.5 VALUE Input 
The default values for VALUE input on VT125 and VT240 terminals are a 


follows: 


Input Construct 


Unit 


Initial range 


Initial value 
VT125 echo area 
VT240 echo area 


B.1.7 Color Index Values 


Default Value 


1 
0.0—1.0 
0.5 


[(513.0,767.0) x (0,479.0)] in device coordinates 
[(533.0,767.0) x (0,479.0)] device coordinates 


The default color index values for monochrome terminals are as follows: 


Index 
0 


D 
2 
3 


Color 
Background 
Normal 
Dark 

Light 


Red 
Intensity 


0.0 
0.0 
1.0 
1.0 


Green 
Intensity 


0.0 
1.0 
0.0 
1.0 


Blue 
Intensity 


0.0 
0.0 
0.0 
1.0 


The default color index values for color terminals are as follows: 


Index 


Color 


Red 


Green 


Blue 


Intensity 


Ww Nn 
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Black 
Green 
Red 
Blue 


0.0 
0.0 
1.0 
0.0 


Intensity 
0.0 
1.0 
0.0 
0.0 


Intensity 
0.0 
0.0 
0.0 
1.0 


2 WAXstations 


This section describes the information needed to use VAX BASIC graphics 
statements with VAXstations I, II, and II/GPX. 


.2.1 Device Types 


VAXstations I, II, and II/GPX are all device type 41. 


.2.2 Windowing Capabilities 


VAX BASIC graphics does not support calls to the VAXstation windowing 
software; therefore, you should not use VAX BASIC graphics statements 
and calls to the window manager products in the same program. 


Output on VAXstations is displayed on a new window and the output 
display disappears when the new window is closed. There are various 
ways to keep the output display active. For instance, you can include 
SLEEP statements in your programs. 


When performing input, VAX BASIC positions the display window as 
defined by the input echo area (device coordinates). When generating 
output, VAX BASIC positions the display window as defined by the 
current device viewport. 


.2.0 Text Fonts 


VAXstations support the four hardware fonts illustrated in the following 
figures. 
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Figure B-1: VAXstation Font Number 1 
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Figure B-—2: VAXstation Font Number —1 
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Figure B-3: VAXstation Font Number -—2 
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Figure B-4: VAXstation Font Number -—3 
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2.4 Pattern Values 


The following table lists the values for the area style index when the area 
style is set to PATTERN. The default color index values are assumed; 
however, you can change these with the SET COLOR MIX statement. 
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Style Index 
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Appearance 

Black light diagonally woven pattern (25%) 
Red light diagonally woven pattern (25%) 
Green light diagonally woven pattern (25%) 
Blue light diagonally woven pattern (25%) 
Cyan light diagonally woven pattern (25%) 
Magenta light diagonally woven pattern (25%) 
Yellow light diagonally woven pattern (25%) 
Black darker diagonally woven pattern (50%) 
Red darker diagonally woven pattern (50%) 
Green darker diagonally woven pattern (50%) 
Blue darker diagonally woven pattern (50%) 
Cyan darker diagonally woven pattern (50%) 
Magenta darker diagonally woven pattern (50%) 
Yellow darker diagonally woven pattern (50%) 
Black darkest diagonally woven pattern (75%) 
Red darkest diagonally woven pattern (75%) 
Green darkest diagonally woven pattern (75%) 
Blue darkest diagonally woven pattern (75%) 
Cyan darkest diagonally woven pattern (75%) 
Magenta darkest diagonally woven pattern (75%) 
Yellow darkest diagonally woven pattern (75%) 
Black horizontal brick pattern 

Red horizontal brick pattern 

Green horizontal brick pattern 

Blue horizontal brick pattern 

Cyan horizontal brick pattern 

Magenta horizontal brick pattern 

Yellow horizontal brick pattern 

Black vertical brick pattern 


Red vertical brick pattern 


Style Index 


31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
3 
52 
53 
54 
55 
56 
a7 
58 
59 
60 


Appearance 


Green vertical brick pattern 

Blue vertical brick pattern 

Cyan vertical brick pattern 
Magenta vertical brick pattern 
Yellow vertical brick pattern 

Black brick pattern at -45 degrees 
Red brick pattern at -45 degrees 
Green brick pattern at -45 degrees 
Blue brick pattern at -45 degrees 
Cyan brick pattern at -45 degrees 
Magenta brick pattern at -45 degrees 
Yellow brick pattern at -45 degrees 
Black brick pattern at 45 degrees 
Red brick pattern at 45 degrees 
Green brick pattern at 45 degrees 
Blue brick pattern at 45 degrees 
Cyan brick pattern at 45 degrees 
Magenta brick pattern at 45 degrees 
Yellow brick pattern at 45 degrees 
Black finely woven grid 

Red finely woven grid 

Green finely woven grid 

Blue finely woven grid 

Cyan finely woven grid 

Magenta finely woven grid 

Yellow finely woven grid 

Black sparsely woven grid 

Red sparsely woven grid 

Green sparsely woven grid 


Blue sparsely woven grid 
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Style Index 


61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
76 
77 
78 
79 
80 
81 
82 
83 
84 
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Appearance 


Cyan sparsely woven grid 
Magenta sparsely woven grid 
Yellow sparsely woven grid 

Black downward scales (fish-like) 
Red downward scales (fish-like) 
Green downward scales (fish-like) 
Blue downward scales (fish-like) 
Cyan downward scales (fish-like) 
Magenta downward scales (fish-like) 
Yellow downward scales (fish-like) 
Black upward scales 

Red upward scales 

Green upward scales 

Blue upward scales 

Cyan upward scales 

Magenta upward scales 

Yellow upward scales 

Black rightward scales 

Red rightward scales 

Green rightward scales 

Blue rightward scales 

Cyan rightward scales 

Magenta rightward scales 


Yellow rightward scales 


Style Index 


85 
86 
87 
88 
89 
90 
91 
91-203 


2.5 Hatch Values 


Appearance 


Black leftward scales 
Red leftward scales 
Green leftward scales 
Blue leftward scales 
Cyan leftward scales 
Magenta leftward scales 
Yellow leftward scales 


Increasing densities, incrementing first by color, starting at 
1/16 density, incrementing by 1/16, up to 15/16 density 


The following table lists the values for the area style index when the area 
style is set to HATCH. 


Style Index 
-1 
-2 
-3 
-4 


Appearance 

Cross hatching 

Diagonal lines at 45 degrees (50%) 

Diagonal lines at —45 degrees (50%) 
Horizontal lines (50%) 

Vertical lines (50%) 

Diagonal lines at 45 degrees—sparse (12.5%) 
Diagonal lines at -45 degrees—sparse (12.5%) 
Horizontal lines—sparse (12.5%) 

Vertical lines—sparse (12.5%) 

Diagonal lines at 45 degrees (25%) 

Diagonal lines at -45 degrees (25%) 
Horizontal lines (25%) 

Vertical lines (25%) 

Diagonal lines at 45 degrees—sparse (6.25%) 
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Style Index 
-15 
-16 
-17 
-18 
-19 
~20 
-21 
-22 
-23 


B.2.6 Device Coordinates 


Appearance 

Diagonal lines at -45 degrees—sparse (6.25%) 
Horizontal lines—sparse (6.25%) 

Vertical lines—sparse (6.25%) 

Diagonal lines at 45 degrees (75%) 

Diagonal lines at -45 degrees (75%) 
Horizontal lines (75%) 

Vertical lines (75%) 

Diagonal lines at 45 degrees—sparse (50%) 
Diagonal lines at -45 degrees—sparse (50%) 
Horizontal lines—sparse (50%) 

Vertical lines—sparse (50%) 

Diagonal lines at 45 degrees—sparse (75%) 
Diagonal lines at -45 degrees—sparse (75%) 
Horizontal lines—sparse (75%) 

Vertical lines—sparse (75%) 

Horizontal lines—very fine (50%) 

Vertical lines—very fine (50%) 

Finely woven grid 


Sparsely woven grid 


The VAXstation device coordinates have the range ([0,0.3319027] x 
[0,0.2738526]), in meters. 


The VAXstation handler divides the device coordinate range into raster 
units to establish the pixels actually used by the physical device. The 
VAXstation raster unit range is ([0,1011] x [0,834)). 
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2.7 


Input Constructs 


On a VAXstation, you can enter input with the keyboard or the mouse. 

With the keyboard, you press the RETURN key to indicate the comple- 
tion of input. You use the arrow keys to move the cursor. For POINT, 

MULTIPOINT, and VALUE input, you can use the PF3 key to move the 
cursor a shorter distance and the PF4 key to move the cursor a greater 

distance. 


For all input types except STRING, pressing the leftmost mouse button 
enters the input value. The middle button on the mouse causes the input 
to be canceled. You cannot use the keyboard to enter or cancel input. For 
STRING input, use the RETURN key to enter input and the CTRL/U key 
to cancel input. To begin entering MULTIPOINT input, you press and 
release the leftmost button on the mouse, and then move the mouse as 
desired. 


The input units for VAXstations are as follows: 


Input Types Units 
POINT 1 
MULTIPOINT 1 
VALUE 1 
CHOICE 1 
STRING ye 


For all input types, you specify the echo area in device coordinates. The 
device coordinate system origin for VAXstations is in the lower left corner 
of the display surface. By default, the VAXstation handler uses an echo 
area whose lower left corner is located in the lower left corner of the 
display surface (the origin of the device coordinate system). 


If, during input, you move the mouse outside the echo area, mouse 
tracking is disabled until the mouse is once again within the echo area. 


When you request input, the VAXstation handler pops the worksta- 
tion viewport to the top of any other overlapping viewports. Viewport 
appearance before and after the input request is unchanged. 


The sections that follow briefly describe each input type and show initial 
values for each. 
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B.2.7.1 POINT Input 


The default values for POINT input on VAXstations are as follows: 


Input Construct 
Unit 
Initial position 


Echo area 


Default Value 
1 
(0.5, 0.5) in world coordinates 


[(0,0.3286231) x (0,0.2695890)] in device coordi- 
nates (meters) 


If the user attempts to enter a point outside of of the echo area, the 
VAXstation handler ignores the entry. 


B.2.7.2 MULTIPOINT Input 


The default values for MULTIPOINT input on VAXstations are as follows: 


Input Construct 
Unit 
Initial number of points 


Echo area 


B.2.7.3. CHOICE Input 


Default Value 
1 
0 


{(0,0.3286231) x (0,0.2695890)] in device coordi- 
nates (meters) 


The default values for CHOICE input on VAXstations are as follows: 


Input Construct 

Unit 

Echo area 

Initial number of choices 


Default strings 
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Default Value 

1 

{(0,0.02) x (0,0.02)] in device coordinates (meters) 
2 

“YES”, “NO” 


2.7.4 STRING Input 
The default values for STRING input on VAXstations are as follows: 


Input Construct Default Value 

Unit 1 

Initial string Null 

Echo area {(0,0.2) x (0,0.01)] in device coordinates (meters) 


STRING Input Unit 1 


STRING input unit 1 returns a DEC Multinational text string to the calling 
program. 


An underline cursor marks the current position within the string. The 
DELETE key deletes the previous character from the string and erases 
the character from the display. The left and right arrow keys change the 
editing position within the string. Pressing CTRL/A toggles between 
insert and overlay mode. 


You enter STRING input unit 1 by pressing the RETURN key, and you 
cancel input by pressing CTRL/U. 


STRING Input Unit 2 


The string logical input unit 2 returns an SMG Encoded Key value. The 
input request for this unit ends as soon as the user presses a key on the 
keyboard. For more information on STRING input unit 2, refer to the 
documentation for the SMG Run-Time Library Routines. 


2.7.5 VALUE Input 


The echo area must be at least 0.03411 meters wide by 0.01476 meters 
high, so that there is sufficient room to display the digital value repre- 
sentation of the current value. If the echo area is too small, an error is 
generated. 
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The default values for VALUE input on VAXstations are as follows: 


Input Construct Default Value 

Unit 1 

Initial range 0.0—1.0 

Initial value 0.5 

Echo area [(0,0.127) x (0,0.0254)] in device coordinates 
(meters) 


B.2.8 Color Index Values 


The following table lists the default red, green, and blue intensity associ- 
ated with each color index value on monochrome VAXstations. Note that 
the VAXstation workstations use a white background by default. 


Red Green Blue 
Index Color Intensity Intensity Intensity 
0 White 1.0 1.0 1.0 
1 Black 0.0 0.0 0.0 


If you request a shade that is above 50% on the gray scale, the VAXstatio: 
handler uses the black representation; otherwise, it uses the white repre- 
sentation. 


The following table lists the default red, green, and blue intensity as- 
sociated with each color index value. The number of default colors is 
anywhere from 2 to 248, depending on the GPX bit planes. (For more 
information about GPX bit planes, see the VAX GKS documentation.) 
Be aware that these values can be redefined with the SET COLOR MIX 
statement, and that a change to the color intensity associated with red, 
green, or blue alters the color associated with the color index. The first 
eight default colors and the equivalent intensity values are as follows: 
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Red Green Blue Gray 


Index Color Intensity Intensity Intensity Level 
0 White 10 42.10 42:10 £810 
1 Black 0.0 0.0 0.0 0.0 

2 Red 1.0 0.0 0.0 0.30 

3 Green 0.0 1.0 0.0 0.59 

4 Blue 0.0 0.0 1.0 0.11 

5 Cyan 0.0 1.0 1.0 0.60 

6 Magenta 1.0 0.0 1.0 0.41 

7 Yellow 1.0 1.0 0.0 0.89 


Color indices 8 through 32 are random colors defined so that you can 
use any two colors side by side without having difficulty distinguishing 
between colors. Indices 33 through 248 are defined such that first the blue 
intensity value is incremented, then the green intensity, and finally the red 
intensity. 


.3 Color Intensities 


The following chart illustrates the possible colors that you can display 
by supplying the indicated intensity values with the SET COLOR MIX 
statement. 


Figure B—5 presents a chart of 64 colors and their corresponding red, 
green, and blue intensity values. If you are working with a color VT125, 
a VT241, or a VAXstation II/GPX, you can use this color chart as a guide 
when using the SET COLOR MIX statement. The colors presented are the 
64 colors supported by the VT125 and the VT241. 


You should use this color chart as a guide. You should not expect your 
monitor to display the colors exactly as shown. Colors can vary from 
monitor to monitor depending on the following factors: 


e The current background color (affects lighter shades) 

¢ The current brightness and contrast control settings 

¢ The available room light 

e The proximity of the primitive to other colors on the display 
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Figure B-5: Intensity Values for VT125 and VT240 Terminal: 
and VAXstations 


Red Green Blue 

0.0000 0.0000 0.0000 
0.1400 0.1400 1.0000 
1.0000 1.0000 1.0000 
1.0000 0.6133 0.4200 
1.0000 0.5700 0.1400 
0.8538 0.6646 0.2862 
0.8400 0.5600 0.0000 
1.0000 0.1400 0.1400 
0.8400 0.0000 0.0000 
0.8400 0.0000 0.5600 





(Continued on next pag: 
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Figure B-5 (Cont.): Intensity Values for VT125 and VT240 
Terminals and VAXstations 


Red Green Blue 

1.0000 0.1400 0.5700 
0.8538 0.2862 0.6646 
1.0000 0.1400 1.0000 
1.0000 0.4200 0.6133 
0.0000 0.0000 0.5600 
0.6133 0.4200 1.0000 
0.4200 1.0000 1.0000 
0.5600 0.0000 0.8400 
0.7765 0.9235 0.9235 
0.2862 0.6646 0.8538 








(Continued on next page) 
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Figure B—-5 (Cont.): Intensity Values for VT125 and VT240 
Terminals and VAXstations 


Red Green Blue 

0.2862 0.2862 0.8538 
0.4200 0.6133 1.0000 
0.1400 1.0000 1.0000 
0.5700 0.1400 1.0000 
0.0000 0.5600 0.8400 
0.0000 0.0000 0.8400 
0.1400 0.5700 1.0000 
0.0000 0.8400 0.5600 
0.0000 0.5600 0.0000 
0.1400 1.0000 0.5700 





(Continued on next page) 
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Figure B—5 (Cont.): Intensity Values for VT125 and VT240 
Terminals and VAXstations 











Red Green Blue 
0.5700 1.0000 0.1400 wa 
0.1400 1.0000 0.1400 ae 
0.0000 0.8400 0.0000 ps 
0.2862 0.8538 0.2862 oF 
0.5600 0.8400 0.0000 Ee dae ee 
1.0000 1.0000 0.7000 
0.6646 0.8538 0.2862 
0.9235 0.9235 0.7765 

© 0.7119 0.7119 0.4281 





(Continued on next page) 
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Figure B—-5 (Cont.): Intensity Values for VT125 and VT240 
Terminals and VAXstations 


Red Green Blue 

1.0000 1.0000 0.1400 
0.6700 0.6700 0.6700 
0.8521 0.5679 0.5679 
0.3300 0.3300 0.3300 
0.5600 0.0000 0.0000 
0.8538 0.2862 0.2862 
0.6258 0.2142 0.2142 
0.5600 0.0000 0.5600 
0.7119 0.4281 0.7119 
1.0000 0.4200 1.0000 








(Continued on next page 
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Figure B—5 (Cont.): Intensity Values for VT125 and VT240 
Terminals and VAXstations 








Red Green Blue 

1.0000 0.7000 1.0000 
0.6646 0.2862 0.8538 
0.9235 0.7765 0.9235 
0.2142 0.2142 0.6258 
0.7000 1.0000 1.0000 
0.5679 0.5679 0.8521 
0.0000 0.5600 0.5600 
0.4281 0.7119 0.7119 
0.2862 0.8538 0.6646 
0.5679 0.8521 0.5679 








(Continued on next page) 
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Figure B-5 (Cont.): Intensity Values for VT125 and VT240 
Terminals and VAXstations 


Red Green Blue 

0.2142 0.6258 0.2142 
0.4200 1.0000 0.6133 
0.6133 1.0000 0.4200 
1.0000 1.0000 0.4200 
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\CTIVATE DEVICE ® 8-5, 9-4 

\lignment of text ® 4-15, 4-15T 

Angle 
text ® 4-11, 9-42, 9-203 

\ngle measurement ® 4-11 

ANSI ® 1-14 

\rea 
asking about attributes ® 9-6, 9-8, 9-10 
attributes ® 3-23 to 3-29 
changing the color ® 3-3 
changing the style ® 9-149 
changing the style index ® 9-152 


displaying ® 2-13 to 2-15, 9-96, 9-120, 9-126, 


9-137 

\rray 

coordinates in® 2-19, 9-120 

for a matrix ® 6-30 
\SK AREA COLOR ® 3-29, 9-6 
\SK AREA STYLE ® 3-29, 9-8 
\SK AREA STYLE INDEX @ 3-29, 9-10 
\SK CHOICE ECHO AREA ® 9-12 
\SK CLIP ® 5-31, 9-14 
\SK COLOR MIX ® 3-11, 9-16 
\SK DEVICE SIZE ® 7-36, 8-13, 9-18 
\SK DEVICE TYPE ® 8-12, 9-20 
\SK DEVICE VIEWPORT ® 9-22 
\SK DEVICE WINDOW ® 8-15, 9-24 
ASK LINE COLOR ® 3-23, 9-26 
ASK LINE STYLE ® 3-22, 9-28 
\SK MAX COLOR ® 3-10, 9-30 
\SK MAX LINE SIZE ® 3-23, 9-32 
\SK MAX POINT SIZE ® 3-16, 9-34 


INDEX 


ASK POINT COLOR ® 3-16, 9-36 
ASK POINT STYLE ® 3-16, 9-38 
ASK statements ® 1-3T, 1-10 

device identification clause ® 8-2 
ASK STRING ECHO AREA ® 9-40 
ASK TEXT ANGLE ® 4-12, 9-42 
ASK TEXT COLOR ® 9-44 
ASK TEXT EXPAND ® 4-9, 9-46 
ASK TEXT EXTENT ® 4-20, 9-48 
ASK TEXT FONT ® 4-6, 9-51 
ASK TEXT HEIGHT ® 4-6, 9-53 
ASK TEXT JUSTIFY ® 4-20, 9-55 
ASK TEXT PATH ® 4-14, 9-57 
ASK TEXT POINT ® 4-20, 9-59 
ASK TEXT SPACE ® 4-10, 9-62 
ASK TRANSFORMATION ® 9-64 
ASK TRANSFORMATION LIST ® 9-66 
ASK VALUE ECHO AREA ® 9-68 
ASK VIEWPORT @® 5-19, 9-70 
ASK WINDOW ® 5-7, 5-19, 9-72 
Aspect ratio ® 5-14, 8-18 to 8-20, 9-164, 9-167 
ASSIGN command (DCL) ® 1-2, 8-4 
Attributes ® 3-1 to 3-29 

area ® 3-23 to 3-29 

color ® 3-2 to 3-11, B-21F 

color on VAXstation ® B-20 

initial values ® 8-7 

line ® 3-17 to 3-23 

point ® 3-11 to 3-17 

text ® 4-1 to 4-22, 9-236 

text in pictures ® 9-235 
Attribute statements ® 1-3T, 1-6 
Axis ® 2-2 


Index—1 





Beam of light ® 2-9 to 2-13 
Boundaries 
world viewport ® 5-12 to 5-15 
world window ® 5-1 to 5-7 


C 


Cartesian coordinate system ® 2-1 
CHAR precision ® 4-3 
CHOICE input ® 7-2F, 7-6 to 7-11, 9-104 
echo area® 9-12, 9-154 
on VAXstations ® B-18 
on VT125/240 terminals ® B-5 
setting the initial value ® 7-6, 9-170 
Clauses 
order of optional ® 8-3 
CLEAR ® 8-6, 9-74 
Clipping ® 5-22 to 5-31, 9-14, 9-157 
in a device transformation ® 8-18 
in a picture ® 6-6 
of text® 4-4 
CLOSE DEVICE ® 8-7, 9-76 
Closed shapes 
displaying ® 2-6 
Color ® 9-6, 9-26, 9-36, 9-44 
asking about attributes ® 3-10, 9-6, 9-16, 9-26, 
9-30, 9-36, 9-44 
changing the index ® 3-3 
changing the intensity ® 3-6 
default indices ® 3-2, 3-2T 
default intensities ® 3-6T, 9-17T, 9-162T 
index ® 9-30 
index values on VT 125/240 terminals ® B-6 
intensities ® B-2 1F 
mixing ® 3-7, 9-16 
on monochrome VAXstation ® B-20 
setting ® 3-2 to 3-11, 9-146, 9-187, 9-193, 
9-205 
VAXstation li/GPX @ B-20 
Color chart for VAXstations ® B-2 1F 
Color mix ® 9-161 
Color terminals ® 1-2 
Concatenation point of text ® 4-20 
Control statements ® 1-3T, 1-12 
device identification clause ® 8-2 
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Coordinates ® 2-1 to 2-3 
enclosing with parentheses ® 1-5, 2-2 
for VT 125/240 terminals ® B-3 
in arrays ® 2-19 
VAXstations ® B-16 
Coordinate statements ® 1-3T, 1-11 
Coordinate system ® 2-1 to 2-3, 5-1 
COUNT clause 
in MAT GRAPH statement ® 2-21 
in MAT LOCATE POINTS statement ® 7-13 
in SET INITIAL CHOICE statement ® 7-7 
in SET INITIAL MULTIPOINT statement ® 7-23 


DEACTIVATE DEVICE ® 8-6, 9-78 
Declarations ® 1-10 
Default ® 1-12 to 1-13 
CHOICE value ® 7-2F 
clipping ® 5-22 
color indices ® 3-2T 
color intensities ® 3-6T, 9-17T, 9-162T 
device ® 8-2, 9-129 
device type ® 8-2 
drawing board ® 2-1 to 2-3, 5-1 
input unit ® 7-5 
transformation ® 5-16 
VALUE input ® 7-4 
VAX BASIC ® A-1 
VAX GKS ® A-1 
world viewport ® 5-12 
world window ® 5-1 
Device 
activating ® 8-5 to 8-7, 9-4 
assigning a type ® 8-4 
boundaries ® 8-13, 9-18 
capabilities ® 8-14 
clearing the display ® 9-74 
closing ® 8-7, 9-76 
deactivating ® 8-5 to 8-7, 9-78 
default ® 8-2, 8-6 
default attributes ® 9-140 
default type ® 8-4 
display surface ® 8-13 
identification clauses ® 8-2 
identifying ® 9-129 
identifying multiple ® 8-2 to 8-5 


levice (cont’d.) 
input types ® 7-2 to 7-5 
logical name ® 8-5, 9-129 
measurements ® 8-13 
multiple ® 8-1 to 8-14 
multiple VAXstation windows ® 7-1, 8-2 
opening ® 8-1, 8-5, 9-129 
opening multiple ® 8-1 
protection ® 8-1 
queued ® 8-5 
restoring initial state © 8-7 
size®9-18 
supported types ® 8-4, 9-130T 
unspecified ® 8-13 
VAXstations ® B-7 
VT125/240 ®B-1 
evice identification 
default © 8-2 
for VAXstation windows ® 7-1 
evice identification clause 
in statements ® 8-2 
device identification number ® 7-1 
evice transformation ® 8-14 to 8-20, 9-22, 9-24 
evice type ® 8-2, 8-4, 8-12, 9-20, 9-129 
for VAXstations ® B-7 
Jevice types 
assigning ® 1-2 
evice viewport ® 8-16 to 8-20, 9-22 
setting ® 9-164 
Yevice window ® 8-15 to 8-20, 9-24, 9-167 
irection of text® 4-13 
RAW ® 1-8, 2-24, 6-1 to 6-36, 9-80, 9-133 
with a user matrix ® 6-32 
WITH ROTATE ® 6-21 
WITH SCALE ® 6-19 
WITH SHEAR ® 6-24 
WITH SHIFT ® 6-14 
WITH TRANSFORM ® 6-35 
with transformation functions ® 6-13 to 6-36 
drawing board 
default ® 2-1 to 2-3 


‘cho area ® 7-36 to 7-37, 9-12, 9-40, 9-68, 


9-154, 9-200, 9-224 
:ND PICTURE ® 6-2, 9-91 


Error messages ® 1-14 
Example 
libraries in kit ® 1-9 
EXIT PICTURE ® 6-2, 9-92 
Expansion factor of text ® 4-8, 9-46, 9-208 
EXTERNAL ® 2-23, 6-1, 6-7 


F 


Fill style © 3-23 to 3-29 
Floating-point declaration ® 1-10 
Font ® 4-1 to 4-6, 9-51, 9-210 
default ® 4-1 
hardware ® 4-1, 4-3, 4-4 
precision ® 4-3, 4-6 
selection ® 4-1 to 4-6 
software ® 4-1 
speed of display ® 4-1 
Fonts 
Hershey ® 4-1 
on VAXstations ® B-7 
on VT 125/240 terminals ® B-2 
FORMATS function 
with GRAPH TEXT statement ® 2-18 
Function 
See also Transformation function 
FORMATS ® 2-18 
ROTATE ® 6-21, 9-82, 9-142 
SCALE ® 6-19, 9-81, 9-144 
SHEAR ® 6-24, 9-82, 9-231 
SHIFT ® 6-14, 9-82, 9-233 
TRANSFORM ® 6-35, 9-83, 9-235 
user matrix © 9-83 


GET POINT ® 7-12, 9-93 

GKS (Graphical Kernel System) ® 1-14 
See also VAX GKS 

GKSSWSTYPE ® 1-2, 3-2, 8-4 

GRAPH AREA ® 2-13 to 2-15, 9-96 

Graphical Kernel System (GKS) ® 1-14 
See also VAX GKS 

Graphics input ® 7-1, 7-2F 

Graphics standards ® 1-14 

GRAPH LINES ® 2-5 to 2-8, 9-96 


Index-—3 


GRAPH METAFILE ® 8-10, 9-99 

GRAPH POINTS ® 2-4, 9-96 

GRAPH TEXT ® 2-15 to 2-18, 4-15T, 9-101 
with FORMATS function ® 2-18 


Hatch index ® 9-152 
See also Area 
changing the style ® 3-25 
on VT125/240 terminals ® B-2 
VAXstation ® B-15 
Height of text® 4-6, 5-4, 9-53, 9-213, 9-230, 
9-236 
Height-to-width ratio of text ® 4-8 
Hershey fonts ® 4-1 


Identification 
of devices ® 8-2 
Input 
CHOICE ® 7-6 to 7-11, 9-104 
echo area® 9-154, 9-200, 9-224 
echo areas ® 7-36 to 7-37 
multiple points ® 9-115, 9-123 
MULTIPOINT ® 7-12 to 7-31 
on VT 125/240 terminals ® B-3 
POINT ® 7-12 to 7-31, 9-93, 9-107 
priority of transformations ® 9-185 
STRING ® 7-31 to 7-33, 9-110 
units ® 7-5 
VALUE ® 7-34 to 7-35, 9-112 
VAXstation ® B- 17 
Input priority of transformations ® 7-17, 7-21, 
9-185 
Input statements ® 1-3T, 1-10 
device identification clause ® 8-2 
Input types ® 7-2 to 7-5 
on VAXstations ® B-17 
Integer declarations ® 1-10 
Intensity 
changing color ® 3-6 
values ® B-21F 
International Organization for Standards (ISO) ® 
1-14 
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ISO (International Organization for Standards) ® 
1-14 





J 


Justification of text ® 4-15, 4-15T, 9-55, 9-215 


L 


Library 

picture examples ® 1-9 
Light beam ® 2-9 to 2-13 
Line 

asking about attributes ® 3-22, 9-26, 9-28, 

9-32 

changing the color ® 3-3 

changing the style ® 3-18 to 3-19, 9-28 

changing the width ® 3-19 

curved ® 2-10 to 2-13 

displaying ® 2-5 to 2-13, 9-96, 9-120, 9-126, 

9-137 

style ®3-18T, 9-191 

width ® 9-189 
LIST clause 

in SET INITIAL CHOICE statement ® 7-7 
LOCATE CHOICE ® 7-9, 7-11, 9-104 
LOCATE POINT ® 7-12, 9-107 
LOCATE STRING ® 7-31, 7-33, 9-110 
LOCATE VALUE ® 7-34, 7-35, 9-112 
Login procedures 

GKSSWSTYPE ® 8-4 


MAT ® 9-142, 9-144, 9-231, 9-233, 9-235 
for defining matrices ® 6-32 

MAT GET POINTS ® 7-12, 9-115 

MAT GRAPH ® 2-19 to 2-23 

MAT GRAPH AREA ® 2-19 to 2-23, 9-120 

MAT GRAPH LINES ® 2-19 to 2-23, 9-120 

MAT GRAPH POINTS ® 2-19 to 2-23, 9-120 

MAT LOCATE POINTS ® 7-12, 9-123 

MAT PLOT AREA ® 9-126 

MAT PLOT LINES ® 9-126 

MAT PLOT POINTS ® 9-126 








Aatrix 
for transformation functions ® 6-30 
Neasurement of device ® 8-13 
Aenus ® 7-2F, 9-104 
Aetafile © 8-8 to 8-12 
creating ® 8-8, 9-99 
displaying ® 8-10, 9-99 
Aultiple objects 
displaying ® 2-19 to 2-23 
Aultiple windows 
on VAXstations ® 7-1, 8-2, B-7 
AULTIPOINT input ® 7-4, 7-12 to 7-31, 9-115, 
9-123 
accepting with default transformation ® 7-12 
accepting within pictures ® 7-25 
accepting with multiple transformation ® 7-14 
on VAXstations ® B-18 
on VT 125/240 terminals ® B-4 
setting the initial value ® 7-23, 9-174 


IDC (Normalized Device Coordinate) space ® 5-9 to 


5-10, 8-15 
tormalization transformation ® 5-8 to 5-32, 8-14 
lormalized Device Coordinate space 
See NDC space 


D 


Jbjects 

attributes of © 3-1T 

displaying multiple ® 2-19 to 2-23 
)PEN...FOR GRAPHICS ® 8-1 to 8-5, 8-7, 9-129 
IPTION ANGLE ® 4-11, 6-21, 6-24 
Jutput statements ® 1-3T, 1-5 


p 


-arameters 
in a picture ® 2-24, 6-2 to 6-7, 9-133 
-arentheses 
enclosing coordinates ® 2-2 
for coordinates ® 1-5 
ath of text ® 4-13, 9-57 
attern index ® 9-152 


Pattern index (cont’d.) 


See also area 

changing the style ® 3-25 

on VT 125/240 terminals ® B-2 
VAXstation ® B-11 


PICTURE ® 6-2 
Picture 
clipping in® 6-6 


examples in kit ® 1-9 
exiting from ® 6-2, 9-91, 9-92 
GRAPH statements in ® 6-14 
identifiers © 2-23, 6-1 
invalid statements in ® 6-6 
invoking ® 1-8, 2-23, 6-2 to 6-7, 9-133 
invoking with transformations ® 6-13 to 6-36, 
9-80 
nested ® 6-7 to 6-14, 6-29 
parameters ® 2-23, 6-2 to 6-7 
PLOT statements in ® 6-14 
recursive ® 6-9, 6-30 
rotating ® 6-21 
scaling ® 6-19 
setting the world viewport ® 6-6 
setting the world window ® 6-6 
shearing ® 6-24 
shifting ® 6-14 
statements ® 1-3T, 1-8, 9-133 
PLOT 
output ® 6-14 
with TRANSFORM function ® 6-36 
PLOT AREA ® 9-137 
PLOT LINES ® 2-9 to 2-13, 9-137 
PLOT POINTS ® 9-137 
Point 
asking about attributes ® 3-16, 9-34, 9-36, 
9-38 
changing the color ® 3-3 
changing the size ® 3-13, 9-196 
changing the style ® 3-11, 9-38, 9-198 
displaying ® 2-4, 9-96, 9-120, 9-126, 9-137 
POINT input ® 7-3, 7-12 to 7-31, 9-93, 9-107, 
9-115, 9-123 
accepting with default transformation ® 7-12 
accepting within pictures ® 7-25 
accepting with multiple transformation ® 7-14 
on VAXstations ® B-18 
on VT 125/240 terminals ® B-4 
setting the initial value ® 7-22, 9-177 
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Portability of programs ® 8-5 
Precision of fonts ® 4-3 to 4-6, 4-6 
PRINT statements 
in graphics ® 4-2 
Priority 
of transformations ® 9-66 
of transformations for input ® 7-17 to 7-22, 
9-185 
Privileges for opening terminals ® 8-1 
Protection for multiple devices ® 8-1 


RESTORE GRAPHICS ® 8-7, 9-140 
ROTATE function ® 6-21, 9-80, 9-82, 9-142 


Ss 


SCALE function ® 6-19, 9-80, 9-81, 9-144 
SET AREA COLOR ® 3-3, 9-146 
SET AREA STYLE ®9-149 
SET AREA STYLE INDEX ® 3-25, 9-152 
SET CHOICE ECHO AREA ® 7-36, 9-154 
SET CLIP ® 5-22, 9-157 
SET COLOR MIX ® 3-6T, 9-161 

intensity values ® B-2 1F 
SET DEVICE VIEWPORT ® 8-15, 9-164 
SET DEVICE WINDOW ® 8-15, 9-167 
SET INITIAL CHOICE ® 7-9, 9-170 
SET INITIAL MULTIPOINT ® 7-23, 9-174 
SET INITIAL POINT ® 7-22, 9-177 
SET INITIAL STRING ® 7-33, 9-179 
SET INITIAL VALUE ® 7-34, 9-182 
SET INPUT PRIORITY ® 7-21, 9-185 
SET LINE COLOR ® 3-3, 9-187 
SET LINE SIZE ® 3-19, 9-189 
SET LINE STYLE ®3-18T, 9-191 
SET POINT COLOR ® 3-3, 9-193 
SET POINT SIZE ® 9-196 
SET POINT STYLE ® 3-11, 9-198 
SET PROTECTION/DEVICE command (DCL) ® 8-1 
SET STRING ECHO AREA ® 7-36, 9-200 
SET TEXT ANGLE ® 4-11, 9-203 
SET TEXT COLOR ® 3-3, 9-205 
SET TEXT EXPAND ® 4-8, 9-208 
SET TEXT FONT ® 4-2, 9-210 
SET TEXT HEIGHT ® 4-6, 5-4, 9-213 
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SET TEXT JUSTIFY ® 4-15, 9-215 
SET TEXT PATH ® 4-13, 9-218 
SET TEXT SPACE ® 4-9, 9-220 
SET TRANSFORMATION ® 5-16, 9-222 
SET VALUE ECHO AREA ® 7-36, 9-224 
SET VIEWPORT ® 5-12, 5-17, 9-226 
SET WINDOW ® 5-2, 5-11, 5-17, 9-229 
SHEAR function ® 6-24, 9-80, 9-82, 9-231 
SHIFT function ® 6-14, 9-80, 9-82, 9-233 
Size 

changing for a line ® 3-19 

changing for a point ® 3-13 
Spacing of text ® 4-9, 9-62, 9-220 
Standards 

graphics ® 1-14 
Starting point of text ®4-15T 
Statements ® 1-3T 

ASK ® 1-10 

attribute ® 1-6 

control ® 1-12 

coordinate ® 1-11 

input ® 1-10 

output ® 1-5 

picture ® 1-8 
STRING 

setting the initial value ® 9-179 
STRING input ® 7-4, 7-31 to 7-33, 9-110 

echo area ® 9-40, 9-200 

on VAXstations ® B-19 

on VT 125/240 terminals ® B-5 

setting the initial value © 7-33 
STRING precision ® 4-3 
STROKE precision ® 4-3 
Style 

See also Hatch, Pattern 

changing for a line ® 3-18 

changing for an area ® 3-25 

changing for a point ® 3-11 
Subprograms 

linking ® 6-2 

PICTURE ® 2-23, 6-1 to 6-37 
SYSPRV privileges ® 8-1 


T 


Terminal 
color ® 3-2 


erminal (cont'd.) 
monochrome ® 3-2, 3-24 
VAXstation ® B-7 
VT 125/240 ®B-1 
erminal type 
assigning ® 1-2 
erminal types 
assigning 
See also Device 
ext 
angle ® 4-11 to 4-12, 9-42, 9-203 
asking about attributes ® 9-42 to 9-43 
attributes in pictures ® 9-236 
box dimensions ® 4-20, 9-48 
changing the color ® 3-3 
changing the height ® 5-4 
clipping ® 4-4 
concatenation point ® 4-20, 9-59 
direction ® 9-218 
displaying ® 2-15 to 2-18, 9-101 
expansion factor ® 9-46, 9-208 
extent box ® 9-48 
extent rectangle ® 4-20, 9-48 
font ® 4-1 to 4-6, 9-51, 9-210 
fonts on VAXstations ® B-7 
fonts on VT 125/240 terminals ® B-2 
height ® 4-6 to 4-7, 9-53, 9-213 
height for world window ® 9-213, 9-229 
height-to-width ratio ® 4-8 to 4-9, 9-46, 9-208 
justification ® 4-15 to 4-20, 9-55, 9-215 
path ® 4-13 to 4-14, 9-57, 9-218 
precision ® 4-3, 4-6 
spacing ® 4-4, 4-9 to 4-10, 9-62 
speed of display ® 4-4 
transforming ® 9-236 
‘ext Starting point ® 4-15T 
‘ransformation ® 5-8 to 5-32 
asking about attributes ® 9-22, 9-24, 9-64, 
9-66, 9-70, 9-72 
current ® 5-16, 9-64, 9-70, 9-72, 9-222 
defining ® 5-8 
device ® 8-14 to 8-20, 9-22, 9-24, 9-167 
input priority ® 7-17, 9-185 
list © 9-66 
matrix ® 6-30 to 6-36 
multiple ® 5-16 to 5-22 
normalization ® 8-14, 8-20 


Transformation (cont’d.) 
priority list © 9-66 
setting the current ® 5-16, 9-222 
Transformation function ® 9-80 
combining ® 6-25 
cumulative ® 6-35 
matrices for ® 6-30 
nested ® 6-29 
ROTATE ®6-21 
SCALE ® 6-19 
SHEAR ® 6-24 
SHIFT © 6-14 
TRANSFORM ® 6-35 
user matrix ® 6-31 
with MAT statement ® 6-32 
with TRANSFORM function ® 6-35 
TRANSFORM function ® 6-35, 9-80, 9-83, 9-235 


UNIT clause 
default ® 7-5 

Units for input ® 7-5 

USING TRAN clause 
with LOCATE POINT statement ® 7-16 
with SET INITIAL POINT statement ® 7-22 


V 


VALUE input ® 7-4, 7-34 to 7-35, 9-112 
echo area ® 9-68, 9-224 
on VAXstations ® B-19 
on VT 125/240 terminals ® B-6 
setting the initial value ® 7-34, 9-182 
Variable declaration ® 1-10 
VAX GKS 
declaring routines ® A-3 
direct calls ® A-1 to A-11 
routine arguments ® A-4 
states ® A-1 
VAXstation ® B-7 to B-21 
CHOICE input ® B-18 
color chart ® B-21F 
default input values ® B-17 
device coordinates ® B-16 
environment characteristics ® B-7 
hatches ® B-15 
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VAXstation (cont’d.) 


input types ® B-17 

multiple windows ® 7-1, 8-2 
MULTIPOINT input ® B-18 
output ® 2- 4 

patterns ®B-11 

POINT input ® B-18 

STRING input ® B-19 

text fonts ® B-7 

VALUE input ® B-19 


Viewport ® 5-10 


boundaries ® 9-18, 9-226 
device ® 8-16 to 8-20, 9-22, 9-164 
setting ® 9-70, 9-226 

setting for a picture ® 6-6 

world ® 5-10 to 5-15 


Viewports 


overlapping ® 7-17 to 7-22 


VT125 terminal ® B-1 to B-6 


CHOICE input ® B-5 
color intensities © B-2 1F 
default input values ® B-3 
device coordinates ® B-3 
hatches ® B-2 
MULTIPOINT input ® B-4 
patterns ® B-2 

POINT input ® B-4 
STRING input ® B-5 

text fonts ® B-2 

VALUE input ® B-6 


VT240 terminal ® B-1 to B-6 


CHOICE input ® B-5 
color intensities ® B-21F 
default input values ® B-3 
device coordinates ® B-3 
hatches ® B-2 
MULTIPOINT input ® B-4 
patterns ®B-2 

POINT input ® B-4 
STRING input ® B-5 

text fonts ® B-2 

VALUE input ® B-6 


Window ® 5-10 
boundaries ® 9-229 
device ® 8-15 to 8-20, 9-24, 9-167 
on VAXstations ® 8-2 
setting © 9-72, 9-229 
setting fora picture ® 6-6 
world ® 5-1, 5-10, 5-11 
Workstations 
VAXstations ® B-7 
VT 125/240 terminals ® B- 1 
World viewport ® 5-10 to 5-15 
setting ® 5-12, 9-226 
setting for a picture ® 6-6 
World window ® 5-1 to 5-7 
setting © 5-1, 9-229 
setting for a picture ® 6-6 


X 


X-axis ® 2-2 
X-coordinate ® 2-2 


Y 


Y-axis ® 2-2 
Y-coordinate ® 2-2 








Ww 


Width 
changing for a line ® 3-19 
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Programming with 
VAX BASIC Graphics 
Al-HY 14A—-TE 





READER’S Note: This form is for document comments only. 
DIGITAL will use comments submitted on this form 

COMMENTS at the company’s discretion. If you require a written 
reply and are eligible to receive one under Software 
Performance Report (SPR) service, submit your 
comments on an SPR form. 


Did you find this manual! understandable, usable, and well organized? Please make 
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Did you find errors in this manual? If so, specify the error and the page number. 


Please indicate the type of user/reader that you most nearly represent: 


Assembly language programmer 
Higher-level language programmer 
Occasional programmer (experienced) 
User with little programming experience 
Student programmer 

Other (please specify) 
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